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:
018: package org.apache.commons.beanutils;
019:
020: import java.lang.reflect.InvocationTargetException;
021: import 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: * @author Craig R. McClanahan
031: * @author Ralph Schaer
032: * @author Chris Audley
033: * @author Rey Francois
034: * @author Gregor Rayman
035: * @version $Revision: 555824 $ $Date: 2007-07-13 01:27:15 +0100 (Fri, 13 Jul 2007) $
036: * @see BeanUtilsBean
037: */
038:
039: public class BeanUtils {
040:
041: // ------------------------------------------------------ Private Variables
042:
043: /**
044: * The debugging detail level for this component.
045: *
046: * Note that this static variable will have unexpected side-effects if
047: * this class is deployed in a shared classloader within a container.
048: * However as it is actually completely ignored by this class due to its
049: * deprecated status, it doesn't do any actual harm.
050: *
051: * @deprecated BeanUtils now uses commons-logging for all log messages.
052: * Use your favorite logging tool to configure logging for
053: * this class.
054: */
055: private static int debug = 0;
056:
057: /**
058: * The <code>debug</code> static property is no longer used
059: * @return debug property
060: * @deprecated BeanUtils now uses commons-logging for all log messages.
061: * Use your favorite logging tool to configure logging for
062: * this class.
063: */
064: public static int getDebug() {
065: return (debug);
066: }
067:
068: /**
069: * The <code>debug</code> static property is no longer used
070: * @param newDebug debug property
071: * @deprecated BeanUtils now uses commons-logging for all log messages.
072: * Use your favorite logging tool to configure logging for
073: * this class.
074: */
075: public static void setDebug(int newDebug) {
076: debug = newDebug;
077: }
078:
079: // --------------------------------------------------------- Class Methods
080:
081: /**
082: * <p>Clone a bean based on the available property getters and setters,
083: * even if the bean class itself does not implement Cloneable.</p>
084: *
085: * <p>For more details see <code>BeanUtilsBean</code>.</p>
086: *
087: * @param bean Bean to be cloned
088: * @return the cloned bean
089: *
090: * @exception IllegalAccessException if the caller does not have
091: * access to the property accessor method
092: * @exception InstantiationException if a new instance of the bean's
093: * class cannot be instantiated
094: * @exception InvocationTargetException if the property accessor method
095: * throws an exception
096: * @exception NoSuchMethodException if an accessor method for this
097: * property cannot be found
098: * @see BeanUtilsBean#cloneBean
099: */
100: public static Object cloneBean(Object bean)
101: throws IllegalAccessException, InstantiationException,
102: InvocationTargetException, NoSuchMethodException {
103:
104: return BeanUtilsBean.getInstance().cloneBean(bean);
105:
106: }
107:
108: /**
109: * <p>Copy property values from the origin bean to the destination bean
110: * for all cases where the property names are the same.</p>
111: *
112: * <p>For more details see <code>BeanUtilsBean</code>.</p>
113: *
114: * @param dest Destination bean whose properties are modified
115: * @param orig Origin bean whose properties are retrieved
116: *
117: * @exception IllegalAccessException if the caller does not have
118: * access to the property accessor method
119: * @exception IllegalArgumentException if the <code>dest</code> or
120: * <code>orig</code> argument is null or if the <code>dest</code>
121: * property type is different from the source type and the relevant
122: * converter has not been registered.
123: * @exception InvocationTargetException if the property accessor method
124: * throws an exception
125: * @see BeanUtilsBean#copyProperties
126: */
127: public static void copyProperties(Object dest, Object orig)
128: throws IllegalAccessException, InvocationTargetException {
129:
130: BeanUtilsBean.getInstance().copyProperties(dest, orig);
131: }
132:
133: /**
134: * <p>Copy the specified property value to the specified destination bean,
135: * performing any type conversion that is required.</p>
136: *
137: * <p>For more details see <code>BeanUtilsBean</code>.</p>
138: *
139: * @param bean Bean on which setting is to be performed
140: * @param name Property name (can be nested/indexed/mapped/combo)
141: * @param value Value to be set
142: *
143: * @exception IllegalAccessException if the caller does not have
144: * access to the property accessor method
145: * @exception InvocationTargetException if the property accessor method
146: * throws an exception
147: * @see BeanUtilsBean#copyProperty
148: */
149: public static void copyProperty(Object bean, String name,
150: Object value) throws IllegalAccessException,
151: InvocationTargetException {
152:
153: BeanUtilsBean.getInstance().copyProperty(bean, name, value);
154: }
155:
156: /**
157: * <p>Return the entire set of properties for which the specified bean
158: * provides a read method.</p>
159: *
160: * <p>For more details see <code>BeanUtilsBean</code>.</p>
161: *
162: * @param bean Bean whose properties are to be extracted
163: * @return Map of property descriptors
164: *
165: * @exception IllegalAccessException if the caller does not have
166: * access to the property accessor method
167: * @exception InvocationTargetException if the property accessor method
168: * throws an exception
169: * @exception NoSuchMethodException if an accessor method for this
170: * property cannot be found
171: * @see BeanUtilsBean#describe
172: */
173: public static Map describe(Object bean)
174: throws IllegalAccessException, InvocationTargetException,
175: NoSuchMethodException {
176:
177: return BeanUtilsBean.getInstance().describe(bean);
178: }
179:
180: /**
181: * <p>Return the value of the specified array property of the specified
182: * bean, as a String array.</p>
183: *
184: * <p>For more details see <code>BeanUtilsBean</code>.</p>
185: *
186: * @param bean Bean whose property is to be extracted
187: * @param name Name of the property to be extracted
188: * @return The array property value
189: *
190: * @exception IllegalAccessException if the caller does not have
191: * access to the property accessor method
192: * @exception InvocationTargetException if the property accessor method
193: * throws an exception
194: * @exception NoSuchMethodException if an accessor method for this
195: * property cannot be found
196: * @see BeanUtilsBean#getArrayProperty
197: */
198: public static String[] getArrayProperty(Object bean, String name)
199: throws IllegalAccessException, InvocationTargetException,
200: NoSuchMethodException {
201:
202: return BeanUtilsBean.getInstance().getArrayProperty(bean, name);
203: }
204:
205: /**
206: * <p>Return the value of the specified indexed property of the specified
207: * bean, as a String.</p>
208: *
209: * <p>For more details see <code>BeanUtilsBean</code>.</p>
210: *
211: * @param bean Bean whose property is to be extracted
212: * @param name <code>propertyname[index]</code> of the property value
213: * to be extracted
214: * @return The indexed property's value, converted to a String
215: *
216: * @exception IllegalAccessException if the caller does not have
217: * access to the property accessor method
218: * @exception InvocationTargetException if the property accessor method
219: * throws an exception
220: * @exception NoSuchMethodException if an accessor method for this
221: * property cannot be found
222: * @see BeanUtilsBean#getIndexedProperty(Object, String)
223: */
224: public static String getIndexedProperty(Object bean, String name)
225: throws IllegalAccessException, InvocationTargetException,
226: NoSuchMethodException {
227:
228: return BeanUtilsBean.getInstance().getIndexedProperty(bean,
229: name);
230:
231: }
232:
233: /**
234: * Return the value of the specified indexed property of the specified
235: * bean, as a String. The index is specified as a method parameter and
236: * must *not* be included in the property name expression
237: *
238: * <p>For more details see <code>BeanUtilsBean</code>.</p>
239: *
240: * @param bean Bean whose property is to be extracted
241: * @param name Simple property name of the property value to be extracted
242: * @param index Index of the property value to be extracted
243: * @return The indexed property's value, converted to a String
244: *
245: * @exception IllegalAccessException if the caller does not have
246: * access to the property accessor method
247: * @exception InvocationTargetException if the property accessor method
248: * throws an exception
249: * @exception NoSuchMethodException if an accessor method for this
250: * property cannot be found
251: * @see BeanUtilsBean#getIndexedProperty(Object, String, int)
252: */
253: public static String getIndexedProperty(Object bean, String name,
254: int index) throws IllegalAccessException,
255: InvocationTargetException, NoSuchMethodException {
256:
257: return BeanUtilsBean.getInstance().getIndexedProperty(bean,
258: name, index);
259:
260: }
261:
262: /**
263: * </p>Return the value of the specified indexed property of the specified
264: * bean, as a String.</p>
265: *
266: * <p>For more details see <code>BeanUtilsBean</code>.</p>
267: *
268: * @param bean Bean whose property is to be extracted
269: * @param name <code>propertyname(index)</code> of the property value
270: * to be extracted
271: * @return The mapped property's value, converted to a String
272: *
273: * @exception IllegalAccessException if the caller does not have
274: * access to the property accessor method
275: * @exception InvocationTargetException if the property accessor method
276: * throws an exception
277: * @exception NoSuchMethodException if an accessor method for this
278: * property cannot be found
279: * @see BeanUtilsBean#getMappedProperty(Object, String)
280: */
281: public static String getMappedProperty(Object bean, String name)
282: throws IllegalAccessException, InvocationTargetException,
283: NoSuchMethodException {
284:
285: return BeanUtilsBean.getInstance()
286: .getMappedProperty(bean, name);
287:
288: }
289:
290: /**
291: * </p>Return the value of the specified mapped property of the specified
292: * bean, as a String.</p>
293: *
294: * <p>For more details see <code>BeanUtilsBean</code>.</p>
295: *
296: * @param bean Bean whose property is to be extracted
297: * @param name Simple property name of the property value to be extracted
298: * @param key Lookup key of the property value to be extracted
299: * @return The mapped property's value, converted to a String
300: *
301: * @exception IllegalAccessException if the caller does not have
302: * access to the property accessor method
303: * @exception InvocationTargetException if the property accessor method
304: * throws an exception
305: * @exception NoSuchMethodException if an accessor method for this
306: * property cannot be found
307: * @see BeanUtilsBean#getMappedProperty(Object, String, String)
308: */
309: public static String getMappedProperty(Object bean, String name,
310: String key) throws IllegalAccessException,
311: InvocationTargetException, NoSuchMethodException {
312:
313: return BeanUtilsBean.getInstance().getMappedProperty(bean,
314: name, key);
315:
316: }
317:
318: /**
319: * <p>Return the value of the (possibly nested) property of the specified
320: * name, for the specified bean, as a String.</p>
321: *
322: * <p>For more details see <code>BeanUtilsBean</code>.</p>
323: *
324: * @param bean Bean whose property is to be extracted
325: * @param name Possibly nested name of the property to be extracted
326: * @return The nested property's value, converted to a String
327: *
328: * @exception IllegalAccessException if the caller does not have
329: * access to the property accessor method
330: * @exception IllegalArgumentException if a nested reference to a
331: * property returns null
332: * @exception InvocationTargetException if the property accessor method
333: * throws an exception
334: * @exception NoSuchMethodException if an accessor method for this
335: * property cannot be found
336: * @see BeanUtilsBean#getNestedProperty
337: */
338: public static String getNestedProperty(Object bean, String name)
339: throws IllegalAccessException, InvocationTargetException,
340: NoSuchMethodException {
341:
342: return BeanUtilsBean.getInstance()
343: .getNestedProperty(bean, name);
344:
345: }
346:
347: /**
348: * <p>Return the value of the specified property of the specified bean,
349: * no matter which property reference format is used, as a String.</p>
350: *
351: * <p>For more details see <code>BeanUtilsBean</code>.</p>
352: *
353: * @param bean Bean whose property is to be extracted
354: * @param name Possibly indexed and/or nested name of the property
355: * to be extracted
356: * @return The property's value, converted to a String
357: *
358: * @exception IllegalAccessException if the caller does not have
359: * access to the property accessor method
360: * @exception InvocationTargetException if the property accessor method
361: * throws an exception
362: * @exception NoSuchMethodException if an accessor method for this
363: * property cannot be found
364: * @see BeanUtilsBean#getProperty
365: */
366: public static String getProperty(Object bean, String name)
367: throws IllegalAccessException, InvocationTargetException,
368: NoSuchMethodException {
369:
370: return BeanUtilsBean.getInstance().getProperty(bean, name);
371:
372: }
373:
374: /**
375: * <p>Return the value of the specified simple property of the specified
376: * bean, converted to a String.</p>
377: *
378: * <p>For more details see <code>BeanUtilsBean</code>.</p>
379: *
380: * @param bean Bean whose property is to be extracted
381: * @param name Name of the property to be extracted
382: * @return The property's value, converted to a String
383: *
384: * @exception IllegalAccessException if the caller does not have
385: * access to the property accessor method
386: * @exception InvocationTargetException if the property accessor method
387: * throws an exception
388: * @exception NoSuchMethodException if an accessor method for this
389: * property cannot be found
390: * @see BeanUtilsBean#getSimpleProperty
391: */
392: public static String getSimpleProperty(Object bean, String name)
393: throws IllegalAccessException, InvocationTargetException,
394: NoSuchMethodException {
395:
396: return BeanUtilsBean.getInstance()
397: .getSimpleProperty(bean, name);
398:
399: }
400:
401: /**
402: * <p>Populate the JavaBeans properties of the specified bean, based on
403: * the specified name/value pairs.</p>
404: *
405: * <p>For more details see <code>BeanUtilsBean</code>.</p>
406: *
407: * @param bean JavaBean whose properties are being populated
408: * @param properties Map keyed by property name, with the
409: * corresponding (String or String[]) value(s) to be set
410: *
411: * @exception IllegalAccessException if the caller does not have
412: * access to the property accessor method
413: * @exception InvocationTargetException if the property accessor method
414: * throws an exception
415: * @see BeanUtilsBean#populate
416: */
417: public static void populate(Object bean, Map properties)
418: throws IllegalAccessException, InvocationTargetException {
419:
420: BeanUtilsBean.getInstance().populate(bean, properties);
421: }
422:
423: /**
424: * <p>Set the specified property value, performing type conversions as
425: * required to conform to the type of the destination property.</p>
426: *
427: * <p>For more details see <code>BeanUtilsBean</code>.</p>
428: *
429: * @param bean Bean on which setting is to be performed
430: * @param name Property name (can be nested/indexed/mapped/combo)
431: * @param value Value to be set
432: *
433: * @exception IllegalAccessException if the caller does not have
434: * access to the property accessor method
435: * @exception InvocationTargetException if the property accessor method
436: * throws an exception
437: * @see BeanUtilsBean#setProperty
438: */
439: public static void setProperty(Object bean, String name,
440: Object value) throws IllegalAccessException,
441: InvocationTargetException {
442:
443: BeanUtilsBean.getInstance().setProperty(bean, name, value);
444: }
445:
446: /**
447: * If we're running on JDK 1.4 or later, initialize the cause for the given throwable.
448: *
449: * @param throwable The throwable.
450: * @param cause The cause of the throwable.
451: * @return true if the cause was initialized, otherwise false.
452: */
453: public static boolean initCause(Throwable throwable, Throwable cause) {
454: return BeanUtilsBean.getInstance().initCause(throwable, cause);
455: }
456: }
|