package org.andromda.core.common;
   
   import java.beans.PropertyDescriptor;
   import java.lang.reflect.Method;
   import java.util.Collection;
   import java.util.HashMap;
   import java.util.Map;
   
   import org.apache.commons.lang.StringUtils;
  import org.apache.commons.lang.exception.ExceptionUtils;
  
  
  /***
   * A simple class providing the ability to manipulate properties on java bean objects.
   *
   * @author Chad Brandon
   */
  public final class Introspector
  {
      /***
       * The shared instance.
       */
      private static Introspector instance = null;
  
      /***
       * Gets the shared instance.
       *
       * @return the shared introspector instance.
       */
      public static Introspector instance()
      {
          if (instance == null)
          {
              instance = new Introspector();
          }
          return instance;
      }
  
      /***
       * <p> Indicates whether or not the given <code>object</code> contains a
       * valid property with the given <code>name</code> and <code>value</code>.
       * </p>
       * <p>
       * A valid property means the following:
       * <ul>
       * <li>It exists on the object</li>
       * <li>It is not null on the object</li>
       * <li>If its a boolean value, then it evaluates to <code>true</code></li>
       * <li>If value is not null, then the property matches the given </code>.value</code></li>
       * </ul>
       * All other possibilities return <code>false</code>
       * </p>
       *
       * @param object the object to test for the valid property.
       * @param name the name of the propery for which to test.
       * @param value the value to evaluate against.
       * @return true/false
       */
      public boolean containsValidProperty(
          final Object object,
          final String name,
          final String value)
      {
          boolean valid;
  
          try
          {
              final Object propertyValue = this.getProperty(
                      object,
                      name);
              valid = propertyValue != null;
  
              // if valid is still true, and the propertyValue
              // is not null
              if (valid)
              {
                  // if it's a collection then we check to see if the
                  // collection is not empty
                  if (propertyValue instanceof Collection)
                  {
                      valid = !((Collection)propertyValue).isEmpty();
                  }
                  else
                  {
                      final String valueAsString = String.valueOf(propertyValue);
                      if (StringUtils.isNotEmpty(value))
                      {
                          valid = valueAsString.equals(value);
                      }
                      else if (propertyValue instanceof Boolean)
                      {
                          valid = Boolean.valueOf(valueAsString).booleanValue();
                      }
                  }
              }
          }
          catch (final Throwable throwable)
          {
              valid = false;
         }
         return valid;
     }
 
     /***
      * Sets the property having the given <code>name</code> on the <code>object</code>
      * with the given <code>value</code>.
      *
      * @param object the object on which to set the property.
      * @param name the name of the property to populate.
      * @param value the value to give the property.
      */
     public void setProperty(
         final Object object,
         final String name,
         final Object value)
     {
         this.setNestedProperty(
             object,
             name,
             value);
     }
 
     /***
      * The delimiter used for seperating nested properties.
      */
     private static final char NESTED_DELIMITER = '.';
 
     /***
      * Attempts to set the nested property with the given
      * name of the given object.
      * @param object the object on which to populate the property.
      * @param name the name of the object.
      * @param value the value to populate.
      */
     private void setNestedProperty(
         final Object object,
         String name,
         final Object value)
     {
         if (object != null && name != null && name.length() > 0)
         {
             final int dotIndex = name.indexOf(NESTED_DELIMITER);
             if (dotIndex >= name.length())
             {
                 throw new IntrospectorException("Invalid property call --> '" + name + "'");
             }
             String[] names = name.split("//" + NESTED_DELIMITER);
             Object objectToPopulate = object;
             for (int ctr = 0; ctr < names.length; ctr++)
             {
                 name = names[ctr];
                 if (ctr == names.length - 1)
                 {
                     break;
                 }
                 objectToPopulate = this.internalGetProperty(
                         objectToPopulate,
                         name);
             }
             this.internalSetProperty(
                 objectToPopulate,
                 name,
                 value);
         }
     }
 
     /***
      * Attempts to retrieve the property with the given <code>name</code> on the <code>object</code>.
      *
      * @param object the object to which the property belongs.
      * @param name the name of the property
      * @return the value of the property.
      */
     public final Object getProperty(
         final Object object,
         final String name)
     {
         Object result;
 
         try
         {
             result = this.getNestedProperty(
                     object,
                     name);
         }
         catch (final IntrospectorException throwable)
         {
             // Dont catch our own exceptions.
             // Otherwise get Exception/Cause chain which
             // can hide the original exception.
             throw throwable;
         }
         catch (Throwable throwable)
         {
             throwable = ExceptionUtils.getRootCause(throwable);
 
             // If cause is an IntrospectorException re-throw that exception
             // rather than creating a new one.
             if (throwable instanceof IntrospectorException)
             {
                 throw (IntrospectorException)throwable;
             }
             throw new IntrospectorException(throwable);
         }
         return result;
     }
 
     /***
      * Gets a nested property, that is it gets the properties
      * seperated by '.'.
      *
      * @param object the object from which to retrieve the nested property.
      * @param name the name of the property
      * @return the property value or null if one couldn't be retrieved.
      */
     private Object getNestedProperty(
         final Object object,
         final String name)
     {
         Object property = null;
         if (object != null && name != null && name.length() > 0)
         {
             int dotIndex = name.indexOf(NESTED_DELIMITER);
             if (dotIndex == -1)
             {
                 property = this.internalGetProperty(
                         object,
                         name);
             }
             else
             {
                 if (dotIndex >= name.length())
                 {
                     throw new IntrospectorException("Invalid property call --> '" + name + "'");
                 }
                 final Object nextInstance = this.internalGetProperty(
                         object,
                         name.substring(
                             0,
                             dotIndex));
                 property = getNestedProperty(
                         nextInstance,
                         name.substring(dotIndex + 1));
             }
         }
         return property;
     }
 
     /***
      * Cache for a class's write methods.
      */
     private final Map writeMethodsCache = new HashMap();
 
     /***
      * Gets the writable method for the property.
      *
      * @param object the object from which to retrieve the property method.
      * @param name the name of the property.
      * @return the property method or null if one wasn't found.
      */
     private Method getWriteMethod(
         final Object object,
         final String name)
     {
         Method writeMethod = null;
         final Class objectClass = object.getClass();
         Map classWriteMethods = (Map)this.writeMethodsCache.get(objectClass);
         if (classWriteMethods == null)
         {
             classWriteMethods = new HashMap();
         }
         else
         {
             writeMethod = (Method)classWriteMethods.get(name);
         }
         if (writeMethod == null)
         {
             final PropertyDescriptor descriptor = this.getPropertyDescriptor(
                     object.getClass(),
                     name);
             writeMethod = descriptor != null ? descriptor.getWriteMethod() : null;
             if (writeMethod != null)
             {
                 classWriteMethods.put(
                     name,
                     writeMethod);
                 this.writeMethodsCache.put(
                     objectClass,
                     classWriteMethods);
             }
         }
         return writeMethod;
     }
 
     /***
      * Indicates if the <code>object</code> has a property that
      * is <em>readable</em> with the given <code>name</code>.
      *
      * @param object the object to check.
      * @param name the property to check for.
      */
     public boolean isReadable(
         final Object object,
         final String name)
     {
         return this.getReadMethod(
             object,
             name) != null;
     }
 
     /***
      * Indicates if the <code>object</code> has a property that
      * is <em>writable</em> with the given <code>name</code>.
      *
      * @param object the object to check.
      * @param name the property to check for.
      */
     public boolean isWritable(
         final Object object,
         final String name)
     {
         return this.getWriteMethod(
             object,
             name) != null;
     }
 
     /***
      * Cache for a class's read methods.
      */
     private final Map readMethodsCache = new HashMap();
 
     /***
      * Gets the readable method for the property.
      *
      * @param object the object from which to retrieve the property method.
      * @param name the name of the property.
      * @return the property method or null if one wasn't found.
      */
     private Method getReadMethod(
         final Object object,
         final String name)
     {
         Method readMethod = null;
         final Class objectClass = object.getClass();
         Map classReadMethods = (Map)this.readMethodsCache.get(objectClass);
         if (classReadMethods == null)
         {
             classReadMethods = new HashMap();
         }
         else
         {
             readMethod = (Method)classReadMethods.get(name);
         }
         if (readMethod == null)
         {
             final PropertyDescriptor descriptor = this.getPropertyDescriptor(
                     object.getClass(),
                     name);
             readMethod = descriptor != null ? descriptor.getReadMethod() : null;
             if (readMethod != null)
             {
                 classReadMethods.put(
                     name,
                     readMethod);
                 this.readMethodsCache.put(
                     objectClass,
                     classReadMethods);
             }
         }
         return readMethod;
     }
 
     /***
      * The cache of property descriptors.
      */
     private final Map propertyDescriptorsCache = new HashMap();
 
     /***
      * Retrives the property descriptor for the given type and name of
      * the property.
      *
      * @param type the Class of which we'll attempt to retrieve the property
      * @param name the name of the property.
      * @return the found property descriptor
      */
     private PropertyDescriptor getPropertyDescriptor(
         final Class type,
         final String name)
     {
         PropertyDescriptor propertyDescriptor = null;
         Map classPropertyDescriptors = (Map)this.propertyDescriptorsCache.get(type);
         if (classPropertyDescriptors == null)
         {
             classPropertyDescriptors = new HashMap();
         }
         else
         {
             propertyDescriptor = (PropertyDescriptor)classPropertyDescriptors.get(name);
         }
         
         if (propertyDescriptor == null)
         {
             try
             {
                 final PropertyDescriptor[] descriptors =
                     java.beans.Introspector.getBeanInfo(type).getPropertyDescriptors();
                 final int descriptorNumber = descriptors.length;
                 for (int ctr = 0; ctr < descriptorNumber; ctr++)
                 {
                     final PropertyDescriptor descriptor = descriptors[ctr];
 
                     // - handle names that start with a lowercased letter and have an uppercase as the second letter
                     final String compareName =
                         name.matches("//p{Lower}//p{Upper}.*") ? StringUtils.capitalize(name) : name;
                     if (descriptor.getName().equals(compareName))
                     {
                         propertyDescriptor = descriptor;
                         break;
                     }
                 }
                 if (propertyDescriptor == null && name.indexOf(NESTED_DELIMITER) != -1)
                 {
                     int dotIndex = name.indexOf(NESTED_DELIMITER);
                     if (dotIndex >= name.length())
                     {
                         throw new IntrospectorException("Invalid property call --> '" + name + "'");
                     }
                     final PropertyDescriptor nextInstance =
                         this.getPropertyDescriptor(
                             type,
                             name.substring(
                                 0,
                                 dotIndex));
                     propertyDescriptor =
                         this.getPropertyDescriptor(
                             nextInstance.getPropertyType(),
                             name.substring(dotIndex + 1));
                 }
             }
             catch (final java.beans.IntrospectionException exception)
             {
                 throw new IntrospectorException(exception);
             }
             classPropertyDescriptors.put(
                 name,
                 propertyDescriptor);
             this.propertyDescriptorsCache.put(
                 type,
                 classPropertyDescriptors);
         }
         return propertyDescriptor;
     }
 
     /***
      * Prevents stack-over-flows by storing the objects that
      * are currently being evaluted within {@link #internalGetProperty(Object, String)}.
      */
     private final Map evaluatingObjects = new HashMap();
 
     /***
      * Attempts to get the value of the property with <code>name</code> on the
      * given <code>object</code> (throws an exception if the property
      * is not readable on the object).
      *
      * @param object the object from which to retrieve the property.
      * @param name the name of the property
      * @return the resulting property value
      */
     private Object internalGetProperty(
         final Object object,
         final String name)
     {
         Object property = null;
 
         // - prevent stack-over-flows by checking to make sure
         //   we aren't entering any circular evalutions
         final Object value = this.evaluatingObjects.get(object);
         if (value == null || !value.equals(name))
         {
             this.evaluatingObjects.put(
                 object,
                 name);
             if (object != null || name != null || name.length() > 0)
             {
                 final Method method = this.getReadMethod(
                         object,
                         name);
                 if (method == null)
                 {
                     throw new IntrospectorException("No readable property named '" + name + "', exists on object '" +
                         object + "'");
                 }
                 try
                 {
                     property = method.invoke(
                             object,
                             (Object[])null);
                 }
                 catch (final Throwable throwable)
                 {
                     throw new IntrospectorException(throwable);
                 }
             }
             this.evaluatingObjects.remove(object);
         }
         return property;
     }
 
     /***
      * Attempts to sets the value of the property with <code>name</code> on the
      * given <code>object</code> (throws an exception if the property
      * is not writable on the object).
      *
      * @param object the object from which to retrieve the property.
      * @param name the name of the property to set.
      * @param value the value of the property to set.
      */
     private void internalSetProperty(
         final Object object,
         final String name,
         Object value)
     {
         if (object != null || name != null || name.length() > 0)
         {
             Class expectedType = null;
             if (value != null)
             {
                 final PropertyDescriptor descriptor = this.getPropertyDescriptor(
                         object.getClass(),
                         name);
                 if (descriptor != null)
                 {
                     expectedType = this.getPropertyDescriptor(
                             object.getClass(),
                             name).getPropertyType();
                     value = Converter.convert(
                             value,
                             expectedType);
                 }
             }
             final Method method = this.getWriteMethod(
                     object,
                     name);
             if (method == null)
             {
                 throw new IntrospectorException("No writeable property named '" + name + "', exists on object '" +
                     object + "'");
             }
             try
             {
                 method.invoke(
                     object,
                     new Object[] {value});
             }
             catch (final Throwable throwable)
             {
                 throw new IntrospectorException(throwable);
             }
         }
     }
 
     /***
      * Shuts this instance down and reclaims
      * any resouces used by this instance.
      */
     public void shutdown()
     {
         this.propertyDescriptorsCache.clear();
         this.writeMethodsCache.clear();
         this.readMethodsCache.clear();
         this.evaluatingObjects.clear();
         instance = null;
     }
 }