/* * $Header: /cvs/osworkflow/src/designer/com/opensymphony/workflow/designer/beanutils/PropertyUtilsBean.java,v 1.3 2004/04/16 10:36:29 hani Exp $ * $Revision: 1.3 $ * $Date: 2004/04/16 10:36:29 $ * * ==================================================================== * * The Apache Software License, Version 1.1 * * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights * reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright *    notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright *    notice, this list of conditions and the following disclaimer in *    the documentation and/or other materials provided with the *    distribution. * * 3. The end-user documentation included with the redistribution, *    if any, must include the following acknowledgement: *       "This product includes software developed by the *        Apache Software Foundation (http://www.apache.org/)." *    Alternately, this acknowledgement may appear in the software itself, *    if and wherever such third-party acknowledgements normally appear. * * 4. The names "Apache", "The Jakarta Project", "Commons", and "Apache Software *    Foundation" must not be used to endorse or promote products derived *    from this software without prior written permission. For written *    permission, please contact apache@apache.org. * * 5. Products derived from this software may not be called "Apache", *    "Apache" nor may "Apache" appear in their names without prior *    written permission of the Apache Software Foundation. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * ==================================================================== * * This software consists of voluntary contributions made by many * individuals on behalf of the Apache Software Foundation.  For more * information on the Apache Software Foundation, please see * <http://www.apache.org/>. * */package com.opensymphony.workflow.designer.beanutils;import java.beans.*;import java.lang.reflect.Array;import java.lang.reflect.InvocationTargetException;import java.lang.reflect.Method;import java.util.*;/** * Utility methods for using Java Reflection APIs to facilitate generic * property getter and setter operations on Java objects.  Much of this * code was originally included in <code>BeanUtils</code>, but has been * separated because of the volume of code involved. * <p/> * In general, the objects that are examined and modified using these * methods are expected to conform to the property getter and setter method * naming conventions described in the JavaBeans Specification (Version 1.0.1). * No data type conversions are performed, and there are no usage of any * <code>PropertyEditor</code> classes that have been registered, although * a convenient way to access the registered classes themselves is included. * <p/> * For the purposes of this class, five formats for referencing a particular * property value of a bean are defined, with the layout of an identifying * String in parentheses: * <ul> * <li><strong>Simple (<code>name</code>)</strong> - The specified * <code>name</code> identifies an individual property of a particular * JavaBean.  The name of the actual getter or setter method to be used * is determined using standard JavaBeans instrospection, so that (unless * overridden by a <code>BeanInfo</code> class, a property named "xyz" * will have a getter method named <code>getXyz()</code> or (for boolean * properties only) <code>isXyz()</code>, and a setter method named * <code>setXyz()</code>.</li> * <li><strong>Nested (<code>name1.name2.name3</code>)</strong> The first * name element is used to select a property getter, as for simple * references above.  The object returned for this property is then * consulted, using the same approach, for a property getter for a * property named <code>name2</code>, and so on.  The property value that * is ultimately retrieved or modified is the one identified by the * last name element.</li> * <li><strong>Indexed (<code>name[index]</code>)</strong> - The underlying * property value is assumed to be an array, or this JavaBean is assumed * to have indexed property getter and setter methods.  The appropriate * (zero-relative) entry in the array is selected.  <code>List</code> * objects are now also supported for read/write.  You simply need to define * a getter that returns the <code>List</code></li> * <li><strong>Mapped (<code>name(key)</code>)</strong> - The JavaBean * is assumed to have an property getter and setter methods with an * additional attribute of type <code>java.lang.String</code>.</li> * <li><strong>Combined (<code>name1.name2[index].name3(key)</code>)</strong> - * Combining mapped, nested, and indexed references is also * supported.</li> * </ul> * * @author Craig R. McClanahan * @author Ralph Schaer * @author Chris Audley * @author Rey Fran鏾is * @author Gregor Ra齧an * @author Jan Sorensen * @author Scott Sanders * @version $Revision: 1.3 $ $Date: 2004/04/16 10:36:29 $ * @see PropertyUtils * @since 1.7 */public class PropertyUtilsBean{  private static final PropertyUtilsBean instance = new PropertyUtilsBean();  // --------------------------------------------------------- Class Methods  protected static PropertyUtilsBean getInstance()  {    return instance;  }  // --------------------------------------------------------- Variables  /**   * The cache of PropertyDescriptor arrays for beans we have already   * introspected, keyed by the java.lang.Class of this object.   */  private Map descriptorsCache = null;  private Map mappedDescriptorsCache = null;  // ---------------------------------------------------------- Constructors  /**   * Base constructor   */  public PropertyUtilsBean()  {    descriptorsCache = new HashMap();    mappedDescriptorsCache = new HashMap();  }  // --------------------------------------------------------- Public Methods  /**   * Clear any cached property descriptors information for all classes   * loaded by any class loaders.  This is useful in cases where class   * loaders are thrown away to implement class reloading.   */  public void clearDescriptors()  {    descriptorsCache.clear();    mappedDescriptorsCache.clear();    Introspector.flushCaches();  }  /**   * <p>Copy property values from the "origin" bean to the "destination" bean   * for all cases where the property names are the same (even though the   * actual getter and setter methods might have been customized via   * <code>BeanInfo</code> classes).  No conversions are performed on the   * actual property values -- it is assumed that the values retrieved from   * the origin bean are assignment-compatible with the types expected by   * the destination bean.</p>   * <p/>   * <p>If the origin "bean" is actually a <code>Map</code>, it is assumed   * to contain String-valued <strong>simple</strong> property names as the keys, pointing   * at the corresponding property values that will be set in the destination   * bean.<strong>Note</strong> that this method is intended to perform   * a "shallow copy" of the properties and so complex properties   * (for example, nested ones) will not be copied.</p>   *   * @param dest Destination bean whose properties are modified   * @param orig Origin bean whose properties are retrieved   * @throws IllegalAccessException    if the caller does not have   *                                   access to the property accessor method   * @throws IllegalArgumentException  if the <code>dest</code> or   *                                   <code>orig</code> argument is null   * @throws InvocationTargetException if the property accessor method   *                                   throws an exception   * @throws NoSuchMethodException     if an accessor method for this   *                                   propety cannot be found   */  public void copyProperties(Object dest, Object orig) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException  {    if(dest == null)    {      throw new IllegalArgumentException("No destination bean specified");    }    if(orig == null)    {      throw new IllegalArgumentException("No origin bean specified");    }    if(orig instanceof Map)    {      Iterator names = ((Map)orig).keySet().iterator();      while(names.hasNext())      {        String name = (String)names.next();        if(isWriteable(dest, name))        {          Object value = ((Map)orig).get(name);          setSimpleProperty(dest, name, value);        }      }    }    else /* if (orig is a standard JavaBean) */    {      PropertyDescriptor origDescriptors[] = getPropertyDescriptors(orig);      for(int i = 0; i < origDescriptors.length; i++)      {        String name = origDescriptors[i].getName();        if(isReadable(orig, name))        {          if(isWriteable(dest, name))          {            Object value = getSimpleProperty(orig, name);            setSimpleProperty(dest, name, value);          }        }      }    }  }  /**   * <p>Return the entire set of properties for which the specified bean   * provides a read method.  This map contains the unconverted property   * values for all properties for which a read method is provided   * (i.e. where the <code>getReadMethod()</code> returns non-null).</p>   * <p/>   * <p><strong>FIXME</strong> - Does not account for mapped properties.</p>   *   * @param bean Bean whose properties are to be extracted   * @throws IllegalAccessException    if the caller does not have   *                                   access to the property accessor method   * @throws IllegalArgumentException  if <code>bean</code> is null   * @throws InvocationTargetException if the property accessor method   *                                   throws an exception   * @throws NoSuchMethodException     if an accessor method for this   *                                   propety cannot be found   */  public Map describe(Object bean) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException  {    if(bean == null)    {      throw new IllegalArgumentException("No bean specified");    }    Map description = new HashMap();    PropertyDescriptor descriptors[] = getPropertyDescriptors(bean);    for(int i = 0; i < descriptors.length; i++)    {      String name = descriptors[i].getName();      if(descriptors[i].getReadMethod() != null)        description.put(name, getProperty(bean, name));    }    return (description);  }  /**   * Return the value of the specified indexed property of the specified   * bean, with no type conversions.  The zero-relative index of the   * required value must be included (in square brackets) as a suffix to   * the property name, or <code>IllegalArgumentException</code> will be   * thrown.  In addition to supporting the JavaBeans specification, this   * method has been extended to support <code>List</code> objects as well.   *   * @param bean Bean whose property is to be extracted   * @param name <code>propertyname[index]</code> of the property value   *             to be extracted   * @throws ArrayIndexOutOfBoundsException if the specified index   *                                        is outside the valid range for the underlying array   * @throws IllegalAccessException         if the caller does not have   *                                        access to the property accessor method   * @throws IllegalArgumentException       if <code>bean</code> or   *                                        <code>name</code> is null   * @throws InvocationTargetException      if the property accessor method   *                                        throws an exception   * @throws NoSuchMethodException          if an accessor method for this   *                                        propety cannot be found   */  public Object getIndexedProperty(Object bean, String name) throws IllegalAccessException, InvocationTargetException, NoSuchMethodException  {    if(bean == null)    {      throw new IllegalArgumentException("No bean specified");    }    if(name == null)    {      throw new IllegalArgumentException("No name specified");    }    // Identify the index of the requested individual property    int delim = name.indexOf(PropertyUtils.INDEXED_DELIM);    int delim2 = name.indexOf(PropertyUtils.INDEXED_DELIM2);    if((delim < 0) || (delim2 <= delim))    {      throw new IllegalArgumentException("Invalid indexed property '" + name + "'");    }    int index = -1;    try    {      String subscript = name.substring(delim + 1, delim2);      index = Integer.parseInt(subscript);    }    catch(NumberFormatException e)    {      throw new IllegalArgumentException("Invalid indexed property '" + name + "'");    }    name = name.substring(0, delim);    // Request the specified indexed property value    return (getIndexedProperty(bean, name, index));  }  /**   * Return the value of the specified indexed property of the specified   * bean, with no type conversions.  In addition to supporting the JavaBeans   * specification, this method has been extended to support   * <code>List</code> objects as well.   *   * @param bean  Bean whose property is to be extracted