/*

  * Copyright 2005-2007 The Kuali Foundation

  * 

  * Licensed under the Educational Community License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  * 

  * http://www.opensource.org/licenses/ecl2.php

  * 

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.kuali.rice.kns.util;

 import java.beans.PropertyDescriptor;

 import java.io.ByteArrayInputStream;

 import java.io.ByteArrayOutputStream;

 import java.io.ObjectInputStream;

 import java.io.ObjectOutputStream;

 import java.io.Serializable;

 import java.lang.reflect.Field;

 import java.lang.reflect.InvocationTargetException;

 import java.security.MessageDigest;

 import java.util.Collection;

 import java.util.Iterator;

 import java.util.List;

 import java.util.Map;

 import org.apache.commons.beanutils.NestedNullException;

 import org.apache.commons.beanutils.PropertyUtils;

 import org.apache.commons.lang.StringUtils;

 import org.apache.log4j.Logger;

 import org.apache.ojb.broker.core.proxy.ProxyHelper;

 import org.hibernate.collection.PersistentBag;

 import org.kuali.rice.kns.bo.BusinessObject;

 import org.kuali.rice.kns.bo.ExternalizableBusinessObject;

 import org.kuali.rice.kns.bo.PersistableBusinessObject;

 import org.kuali.rice.kns.bo.PersistableBusinessObjectExtension;

 import org.kuali.rice.kns.service.KNSServiceLocator;

 import org.kuali.rice.kns.service.ModuleService;

 import org.kuali.rice.kns.service.PersistenceStructureService;

 import org.kuali.rice.kns.util.cache.CopiedObject;

 import org.kuali.rice.kns.web.format.CollectionFormatter;

 import org.kuali.rice.kns.web.format.FormatException;

 import org.kuali.rice.kns.web.format.Formatter;

 /**

  * This class contains various Object, Proxy, and serialization utilities.

  */

 public class ObjectUtils {

     private static final Logger LOG = Logger.getLogger(ObjectUtils.class);

     private ObjectUtils() {

     }

     /**

      * Uses Serialization mechanism to create a deep copy of the given Object. As a special case, deepCopy of null returns null,

      * just to make using this method simpler. For a detailed discussion see:

      * http://www.javaworld.com/javaworld/javatips/jw-javatip76.html

      * 

      * @param src

      * @return deep copy of the given Serializable

      */

     public static Serializable deepCopy(Serializable src) {

         CopiedObject co = deepCopyForCaching(src);

         return co.getContent();

     }

     /**

      * Uses Serialization mechanism to create a deep copy of the given Object, and returns a CacheableObject instance containing the

      * deepCopy and its size in bytes. As a special case, deepCopy of null returns a cacheableObject containing null and a size of

      * 0, to make using this method simpler. For a detailed discussion see:

      * http://www.javaworld.com/javaworld/javatips/jw-javatip76.html

      * 

      * @param src

      * @return CopiedObject containing a deep copy of the given Serializable and its size in bytes

      */

     public static CopiedObject deepCopyForCaching(Serializable src) {

         CopiedObject co = new CopiedObject();

         co.setContent( src );

         return co;

     }

     /**

      * Converts the object to a byte array using the output stream.

      * 

      * @param object

      * @return byte array of the object

      */

     public static byte[] toByteArray(Object object) throws Exception {

         ObjectOutputStream oos = null;

         try {

             ByteArrayOutputStream bos = new ByteArrayOutputStream(); // A

             oos = new ObjectOutputStream(bos); // B

             // serialize and pass the object

             oos.writeObject(object); // C

             // oos.flush(); // D

             return bos.toByteArray();

         }

         catch (Exception e) {

             LOG.warn("Exception in ObjectUtil = " + e);

             throw (e);

         }

         finally {

             if (oos != null) {

                 oos.close();

             }

         }

     }

     /**

      * reconsitiutes the object that was converted into a byte array by toByteArray

      * @param bytes

      * @return

      * @throws Exception

      */

     public static Object fromByteArray(byte[] bytes) throws Exception {

         ObjectInputStream ois = null;

         try {

             ByteArrayInputStream bis = new ByteArrayInputStream(bytes);

             ois = new ObjectInputStream(bis);

             Object obj = ois.readObject();

             return obj;

         }

         catch (Exception e) {

             LOG.warn("Exception in ObjectUtil = " + e);

             throw (e);

         }

         finally {

             if (ois != null) {

                 ois.close();

             }

         }

     }

     /**

      * use MD5 to create a one way hash of an object

      * 

      * @param object

      * @return

      */

     public static String getMD5Hash(Object object) throws Exception {

         try {

             MessageDigest md = MessageDigest.getInstance("MD5");

             md.update(toByteArray(object));

             return new String(md.digest());

         }

         catch (Exception e) {

             LOG.warn(e);

             throw e;

         }

     }

     /**

      * Creates a new instance of a given BusinessObject, copying fields specified in template from the given source BO. For example,

      * this can be used to create an AccountChangeDetail based on a particular Account.

      * 

      * @param template a map defining the relationships between the fields of the newly created BO, and the source BO.  For each K (key), V (value)

      * entry, the value of property V on the source BO will be assigned to the K property of the newly created BO

      * 

      * @see org.kuali.rice.kns.maintenance.util.MaintenanceUtils

      * 

      * @throws NoSuchMethodException

      * @throws InvocationTargetException

      * @throws IllegalAccessException

      * @throws FormatException

      */

     public static BusinessObject createHybridBusinessObject(Class businessObjectClass, BusinessObject source, Map<String, String> template) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         BusinessObject obj = null;

         try {

                     ModuleService moduleService = KNSServiceLocator.getKualiModuleService().getResponsibleModuleService(businessObjectClass);

                     if (moduleService != null && moduleService.isExternalizable(businessObjectClass))

                             obj = (BusinessObject)moduleService.createNewObjectFromExternalizableClass(businessObjectClass);

                     else

                             obj = (BusinessObject) businessObjectClass.newInstance();

         }

         catch (Exception e) {

             throw new RuntimeException("Cannot instantiate " + businessObjectClass.getName(), e);

         }

         createHybridBusinessObject(obj, source, template);

         return obj;

     }

     public static void createHybridBusinessObject(BusinessObject businessObject, BusinessObject source, Map<String, String> template) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         for (String name : template.keySet()) {

             String sourcePropertyName = template.get(name);

             setObjectProperty(businessObject, name, easyGetPropertyType(source, sourcePropertyName), getPropertyValue(source, sourcePropertyName));

         }

     }

     /**

      * This method simply uses PojoPropertyUtilsBean logic to get the Class of a Class property.

      * This method does not have any of the logic needed to obtain the Class of an element of a Collection specified in the DataDictionary.

      * 

      * @param object An instance of the Class of which we're trying to get the property Class.

      * @param propertyName The name of the property.

      * @return

      * 

      * @throws IllegalAccessException

      * @throws NoSuchMethodException

      * @throws InvocationTargetException

      */

     static public Class easyGetPropertyType(Object object, String propertyName) throws IllegalAccessException, NoSuchMethodException, InvocationTargetException {

         // FIXME (laran) This dependence should be inverted. Instead of having a core class

         // depend on PojoPropertyUtilsBean, which is in the web layer, the web layer

         // should depend downward to the core.

         return PropertyUtils.getPropertyType(object, propertyName);

     }

     /**

      * Returns the type of the property in the object. This implementation is not smart enough to look through a Collection to get the property type

      * of an attribute of an element in the collection.

      * 

      * NOTE: A patch file attached to https://test.kuali.org/jira/browse/KULRNE-4435 contains a modified version of this method which IS smart enough

      * to look through Collections. This patch is currently under review.

      * 

      * @param object An instance of the Class for which we're trying to get the property type.

      * @param propertyName The name of the property of the Class the Class of which we're trying to get. Dot notation is used to separate properties.

      *                     TODO: The rules about this dot notation needs to be explained in Confluence using examples. 

      * @param persistenceStructureService Needed to get the type of elements in a Collection from OJB. 

      * 

      * @return Object will be null if any parent property for the given property is null.

      */

     public static Class getPropertyType(Object object, String propertyName, PersistenceStructureService persistenceStructureService) {

                 if (object == null || propertyName == null) {

                         throw new RuntimeException("Business object and property name can not be null");

                 }

                 Class propertyType = null;

                 try {

                         try {

                                 // Try to simply use the default or simple way of getting the property type.

                                 propertyType = PropertyUtils.getPropertyType(object, propertyName);

                         } catch (IllegalArgumentException ex) {

                                 // swallow the exception, propertyType stays null

                         } catch (NoSuchMethodException nsme) {

                                 // swallow the exception, propertyType stays null

                         }

                         // if the property type as determined from the object is PersistableBusinessObject,

                         // then this must be an extension attribute -- attempt to get the property type from the

                         // persistence structure service

                         if (propertyType != null && propertyType.equals(PersistableBusinessObjectExtension.class)) {

                                 propertyType = persistenceStructureService.getBusinessObjectAttributeClass(

                                                 ProxyHelper.getRealClass(object), propertyName);

                         }

                         // If the easy way didn't work ...

                         if (null == propertyType && -1 != propertyName.indexOf('.')) {

                                 if (null == persistenceStructureService) {

                                         LOG.info("PropertyType couldn't be determined simply and no PersistenceStructureService was given. If you pass in a PersistenceStructureService I can look in other places to try to determine the type of the property.");

                                 } else {

                                         String prePeriod = StringUtils.substringBefore(propertyName, ".");

                                         String postPeriod = StringUtils.substringAfter(propertyName, ".");

                                         Class prePeriodClass = getPropertyType(object, prePeriod, persistenceStructureService);

                                         Object prePeriodClassInstance = prePeriodClass.newInstance();

                                         propertyType = getPropertyType(prePeriodClassInstance, postPeriod, persistenceStructureService);

                                 }

                         } else if (Collection.class.isAssignableFrom(propertyType)) {

                                 Map<String, Class> map = persistenceStructureService.listCollectionObjectTypes(object.getClass());

                                 propertyType = map.get(propertyName);

                         }

                 } catch (Exception e) {

                         LOG.debug("unable to get property type for " + propertyName + " " + e.getMessage());

                         // continue and return null for propertyType

                 }

                 return propertyType;

         }

     /**

      * Returns the value of the property in the object.

      * 

      * @param businessObject

      * @param propertyName

      * 

      * @return Object will be null if any parent property for the given property is null.

      */

     public static Object getPropertyValue(Object businessObject, String propertyName) {

         if (businessObject == null || propertyName == null) {

             throw new RuntimeException("Business object and property name can not be null");

         }

         Object propertyValue = null;

         try {

             propertyValue = PropertyUtils.getProperty(businessObject, propertyName);

         } catch (NestedNullException e) {

             // continue and return null for propertyValue

         } catch (IllegalAccessException e1) {

             LOG.error("error getting property value for  " + businessObject.getClass() + "." + propertyName + " " + e1.getMessage());

             throw new RuntimeException("error getting property value for  " + businessObject.getClass() + "." + propertyName + " " + e1.getMessage(), e1);

         } catch (InvocationTargetException e1) {

             // continue and return null for propertyValue

         } catch (NoSuchMethodException e1) {

             LOG.error("error getting property value for  " + businessObject.getClass() + "." + propertyName + " " + e1.getMessage());

             throw new RuntimeException("error getting property value for  " + businessObject.getClass() + "." + propertyName + " " + e1.getMessage(),e1);

         }

         return propertyValue;

     }

         /**

          * Gets the property value from the business object, then based on the value

          * type select a formatter and format the value

          * 

          * @param element

          *            BusinessObject instance that contains the property

          * @param propertyName

          *            Name of property in BusinessObject to get value for

          * @param formatter

          *            Default formatter to use (or null)

          * @return Formatted property value as String, or empty string if value is null

          */

         public static String getFormattedPropertyValue(BusinessObject businessObject, String propertyName, Formatter formatter) {

                 String propValue = KNSConstants.EMPTY_STRING;

                 Object prop = ObjectUtils.getPropertyValue(businessObject, propertyName);

                 if (formatter == null) {

                         propValue = formatPropertyValue(prop);

                 } else {

                         final Object formattedValue = formatter.format(prop);

                         if (formattedValue != null) {

                                 propValue = String.valueOf(formattedValue);

                         }

                 }

                 return propValue;

         }

         /**

          * References the data dictionary to find any registered formatter class then if not found checks for associated formatter for the

          * property type. Value is then formatted using the found Formatter

          * 

          * @param element

          *            BusinessObject instance that contains the property

          * @param propertyName

          *            Name of property in BusinessObject to get value for

          * @return Formatted property value as String, or empty string if value is null

          */

         public static String getFormattedPropertyValueUsingDataDictionary(BusinessObject businessObject, String propertyName) {

                 Formatter formatter = getFormatterWithDataDictionary(businessObject, propertyName);

                 return getFormattedPropertyValue(businessObject, propertyName, formatter);

         }

         /**

          * Based on the value type selects a formatter and returns the formatted

          * value as a string

          * 

          * @param propertyValue

          *            Object value to be formatted

          * @return formatted value as a String

          */

         public static String formatPropertyValue(Object propertyValue) {

                 Object propValue = KNSConstants.EMPTY_STRING;

                 Formatter formatter = null;

                 if (propertyValue != null) {

                         if (propertyValue instanceof Collection) {

                                 formatter = new CollectionFormatter();

                         } else {

                                 formatter = Formatter.getFormatter(propertyValue.getClass());

                         }

                         propValue = formatter != null ? formatter.format(propertyValue) : propertyValue;

                 }

                 return propValue != null ? String.valueOf(propValue) : KNSConstants.EMPTY_STRING;

         }

     /**

      * Sets the property of an object with the given value. Converts using the formatter of the type for the property.

      * Note: propertyType does not need passed, is found by util method.

      */

     public static void setObjectProperty(Object bo, String propertyName, Object propertyValue) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         Class propertyType = easyGetPropertyType(bo, propertyName);

         setObjectProperty(bo, propertyName, propertyType, propertyValue);

     }

         /**

          * Sets the property of an object with the given value. Converts using the formatter of the given type if one is found.

          * 

          * @param bo

          * @param propertyName

          * @param propertyType

          * @param propertyValue

          * 

          * @throws NoSuchMethodException

          * @throws InvocationTargetException

          * @throws IllegalAccessException

          */

         public static void setObjectProperty(Object bo, String propertyName, Class propertyType, Object propertyValue)

                         throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

                 // reformat propertyValue, if necessary

                 boolean reformat = false;

                 if (propertyType != null) {

                         if (propertyValue != null && propertyType.isAssignableFrom(String.class)) {

                                 // always reformat if the destination is a String

                                 reformat = true;

                         } else if (propertyValue != null && !propertyType.isAssignableFrom(propertyValue.getClass())) {

                                 // otherwise, only reformat if the propertyValue can't be assigned into the property

                                 reformat = true;

                         }

                         // attempting to set boolean fields to null throws an exception, set to false instead

                         if (boolean.class.isAssignableFrom(propertyType) && propertyValue == null) {

                                 propertyValue = false;

                         }

                 }

                 Formatter formatter = getFormatterWithDataDictionary(bo, propertyName);

                 if (reformat && formatter != null) {

                         LOG.debug("reformatting propertyValue using Formatter " + formatter.getClass().getName());

                         propertyValue = formatter.convertFromPresentationFormat(propertyValue);

                 }

                 // set property in the object

                 PropertyUtils.setNestedProperty(bo, propertyName, propertyValue);

         }

     /**

      * Sets the property of an object with the given value. Converts using the given formatter, if it isn't null.

      * 

      * @param formatter

      * @param bo

      * @param propertyName

      * @param type

      * @param propertyValue

      * 

      * @throws NoSuchMethodException

      * @throws InvocationTargetException

      * @throws IllegalAccessException

      */

     public static void setObjectProperty(Formatter formatter, Object bo, String propertyName, Class type, Object propertyValue) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         // convert value using formatter for type

         if (formatter != null) {

             propertyValue = formatter.convertFromPresentationFormat(propertyValue);

         }

         // set property in the object

         PropertyUtils.setNestedProperty(bo, propertyName, propertyValue);

     }

         /**

          * Returns a Formatter instance for the given property name in the given given business object. First

          * checks if a formatter is defined for the attribute in the data dictionary, is not found then returns

          * the registered formatter for the property type in Formatter

          * 

          * @param bo

          *            - business object instance with property to get formatter for

          * @param propertyName

          *            - name of property to get formatter for

          * @return Formatter instance

          */

         public static Formatter getFormatterWithDataDictionary(Object bo, String propertyName) {

                 Formatter formatter = null;

                 Class boClass = bo.getClass();

                 String boPropertyName = propertyName;

                 // for collections, formatter should come from property on the collection type

                 if (StringUtils.contains(propertyName, "]")) {

                         Object collectionParent = getNestedValue(bo, StringUtils.substringBeforeLast(propertyName, "].") + "]");

                         if (collectionParent != null) {

                                 boClass = collectionParent.getClass();

                                 boPropertyName = StringUtils.substringAfterLast(propertyName, "].");

                         }

                 }

                 Class<? extends Formatter> formatterClass = KNSServiceLocator.getDataDictionaryService().getAttributeFormatter(

                                 boClass, boPropertyName);

                 if (formatterClass == null) {

                         try {

                                 formatterClass = Formatter.findFormatter(getPropertyType(boClass.newInstance(), boPropertyName,

                                                 KNSServiceLocator.getPersistenceStructureService()));

                         } catch (InstantiationException e) {

                                 LOG.warn("Unable to find a formater for bo class " + boClass + " and property " + boPropertyName);

                                 // just swallow the exception and let formatter be null

                         } catch (IllegalAccessException e) {

                                 LOG.warn("Unable to find a formater for bo class " + boClass + " and property " + boPropertyName);

                                 // just swallow the exception and let formatter be null

                         }

                 }

                 if (formatterClass != null) {

                         try {

                                 formatter = formatterClass.newInstance();

                         } catch (Exception e) {

                                 throw new RuntimeException(

                                                 "cannot create new instance of formatter class " + formatterClass.toString(), e);

                         }

                 }

                 return formatter;

         }

     /**

      * Recursive; sets all occurences of the property in the object, its nested objects and its object lists with the given value.

      * 

      * @param bo

      * @param propertyName

      * @param type

      * @param propertyValue

      * 

      * @throws NoSuchMethodException

      * @throws InvocationTargetException

      * @throws IllegalAccessException

      */

     public static void setObjectPropertyDeep(Object bo, String propertyName, Class type, Object propertyValue) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         // Base return cases to avoid null pointers & infinite loops

         if (isNull(bo) || !PropertyUtils.isReadable(bo, propertyName) || (propertyValue != null && propertyValue.equals(getPropertyValue(bo, propertyName))) || (type != null && !type.equals(easyGetPropertyType(bo, propertyName)))) {

             return;

         }

         // need to materialize the updateable collections before resetting the property, because it may be used in the retrieval

         materializeUpdateableCollections(bo);

         // Set the property in the BO

         setObjectProperty(bo, propertyName, type, propertyValue);

         // Now drill down and check nested BOs and BO lists

         PropertyDescriptor[] propertyDescriptors = PropertyUtils.getPropertyDescriptors(bo.getClass());

         for (int i = 0; i < propertyDescriptors.length; i++) {

             PropertyDescriptor propertyDescriptor = propertyDescriptors[i];

             // Business Objects

             if (propertyDescriptor.getPropertyType() != null && (BusinessObject.class).isAssignableFrom(propertyDescriptor.getPropertyType()) && PropertyUtils.isReadable(bo, propertyDescriptor.getName())) {

                 Object nestedBo = getPropertyValue(bo, propertyDescriptor.getName());

                 if ( nestedBo instanceof BusinessObject ) {

                     setObjectPropertyDeep((BusinessObject)nestedBo, propertyName, type, propertyValue);

                 }

             }

             // Lists

             else if (propertyDescriptor.getPropertyType() != null && (List.class).isAssignableFrom(propertyDescriptor.getPropertyType()) && getPropertyValue(bo, propertyDescriptor.getName()) != null) {

                 List propertyList = (List) getPropertyValue(bo, propertyDescriptor.getName());

                 for(Object listedBo: propertyList) {

                     if (listedBo != null && listedBo instanceof BusinessObject) {

                         setObjectPropertyDeep(listedBo, propertyName, type, propertyValue);

                     }

                 } // end for

             }

         } // end for

     }

     /*

     * Recursive up to a given depth; sets all occurences of the property in the object, its nested objects and its object lists with the given value.

     */  

     public static void setObjectPropertyDeep(Object bo, String propertyName, Class type, Object propertyValue, int depth) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         // Base return cases to avoid null pointers & infinite loops

         if (depth == 0 || isNull(bo) || !PropertyUtils.isReadable(bo, propertyName)) {

             return;

         }

         // need to materialize the updateable collections before resetting the property, because it may be used in the retrieval

         materializeUpdateableCollections(bo);

         // Set the property in the BO

         setObjectProperty(bo, propertyName, type, propertyValue);

         // Now drill down and check nested BOs and BO lists

         PropertyDescriptor[] propertyDescriptors = PropertyUtils.getPropertyDescriptors(bo.getClass());

         for (int i = 0; i < propertyDescriptors.length; i++) {

             PropertyDescriptor propertyDescriptor = propertyDescriptors[i];

             // Business Objects

             if (propertyDescriptor.getPropertyType() != null && (BusinessObject.class).isAssignableFrom(propertyDescriptor.getPropertyType()) && PropertyUtils.isReadable(bo, propertyDescriptor.getName())) {

                 Object nestedBo = getPropertyValue(bo, propertyDescriptor.getName());

                 if ( nestedBo instanceof BusinessObject ) {

                     setObjectPropertyDeep((BusinessObject)nestedBo, propertyName, type, propertyValue, depth - 1);

                 }

             }

             // Lists

             else if (propertyDescriptor.getPropertyType() != null && (List.class).isAssignableFrom(propertyDescriptor.getPropertyType()) && getPropertyValue(bo, propertyDescriptor.getName()) != null) {

                 List propertyList = (List) getPropertyValue(bo, propertyDescriptor.getName());

                 // Complete Hibernate Hack - fetches the proxied List into the PersistenceContext and sets it on the BO Copy.

                 if (propertyList instanceof PersistentBag) {

                         try {

                                 PersistentBag bag = (PersistentBag) propertyList;

                                 PersistableBusinessObject pbo = (PersistableBusinessObject) KNSServiceLocator.getEntityManagerFactory().createEntityManager().find(bo.getClass(), bag.getKey());

                                         Field field1 = pbo.getClass().getDeclaredField(propertyDescriptor.getName());

                                         Field field2 = bo.getClass().getDeclaredField(propertyDescriptor.getName());

                                         field1.setAccessible(true);

                                         field2.setAccessible(true);

                                         field2.set(bo, field1.get(pbo));

                                         propertyList = (List) getPropertyValue(bo, propertyDescriptor.getName());;

                         } catch (Exception e) {

                                 LOG.error(e.getMessage(), e);

                         }

                 }

                 // End Complete Hibernate Hack

                 for(Object listedBo: propertyList) {

                     if (listedBo != null && listedBo instanceof BusinessObject) {

                         setObjectPropertyDeep(listedBo, propertyName, type, propertyValue, depth - 1);

                     }

                 } // end for

             }

         } // end for

     }

     /**

      * 

      * This method checks for updateable collections on the business object provided and materializes the corresponding collection proxies

      * 

      * @param bo The business object for which you want unpdateable, proxied collections materialized

      * @throws FormatException

      * @throws IllegalAccessException

      * @throws InvocationTargetException

      * @throws NoSuchMethodException

      */

     public static void materializeUpdateableCollections(Object bo) throws FormatException, IllegalAccessException, InvocationTargetException, NoSuchMethodException {

         if (isNotNull(bo)) {

             PropertyDescriptor[] propertyDescriptors = PropertyUtils.getPropertyDescriptors(bo.getClass());

             for (int i = 0; i < propertyDescriptors.length; i++) {

                 if (KNSServiceLocator.getPersistenceStructureService().hasCollection(bo.getClass(), propertyDescriptors[i].getName()) && KNSServiceLocator.getPersistenceStructureService().isCollectionUpdatable(bo.getClass(), propertyDescriptors[i].getName())) {

                     Collection updateableCollection = (Collection) getPropertyValue(bo, propertyDescriptors[i].getName());

                     if ((updateableCollection != null) && ProxyHelper.isCollectionProxy(updateableCollection)) {

                         materializeObjects(updateableCollection);

                     }

                 }

             }

         }

     }

     /**

      * Removes all query characters from a string.

      * 

      * @param string

      * 

      * @return Cleaned string

      */

     public static String clean(String string) {

         for (int i = 0; i < KNSConstants.QUERY_CHARACTERS.length; i++) {

             string = StringUtils.replace(string, KNSConstants.QUERY_CHARACTERS[i], KNSConstants.EMPTY_STRING);

         }

         return string;

     }

     /**

      * Compares two {@link PersistableBusinessObject} instances for equality of type and key values.

      * 

      * @param bo1

      * @param bo2

      *  

      * @return boolean indicating whether the two objects are equal.

      */

     public static boolean equalByKeys(PersistableBusinessObject bo1, PersistableBusinessObject bo2) {

         boolean equal = true;

         if (bo1 == null && bo2 == null) {

             equal = true;

         }

         else if (bo1 == null || bo2 == null) {

             equal = false;

         }

         else if (!bo1.getClass().getName().equals(bo2.getClass().getName())) {

             equal = false;

         }

         else {

             Map bo1Keys = KNSServiceLocator.getPersistenceService().getPrimaryKeyFieldValues(bo1);

             Map bo2Keys = KNSServiceLocator.getPersistenceService().getPrimaryKeyFieldValues(bo2);

             for (Iterator iter = bo1Keys.keySet().iterator(); iter.hasNext();) {

                 String keyName = (String) iter.next();

                 if (bo1Keys.get(keyName) != null && bo2Keys.get(keyName) != null) {

                     if (!bo1Keys.get(keyName).toString().equals(bo2Keys.get(keyName).toString())) {

                         equal = false;

                     }

                 } else {

                     equal = false;

                 }

             }

         }  

         return equal;

     }

     /**

      * Compares a business object with a List of {@link PersistableBusinessObject}s to determine if an object with the same key as the BO exists in the list.

      * 

      * @param controlList - The list of items to check

      * @param bo - The BO whose keys we are looking for in the controlList

      * 

      * @return boolean

      */

     public static boolean collectionContainsObjectWithIdentitcalKey(Collection<? extends PersistableBusinessObject> controlList, PersistableBusinessObject bo) {

         boolean objectExistsInList = false;

         for (Iterator i = controlList.iterator(); i.hasNext();) {

             if (equalByKeys((PersistableBusinessObject) i.next(), bo)) {

                 return true;

             }

         }

         return objectExistsInList;

     }

     /**

      * Compares a business object with a Collection of {@link PersistableBusinessObject}s to count how many have the same key as the BO.

      * 

      * @param collection - The collection of items to check

      * @param bo - The BO whose keys we are looking for in the collection

      * 

      * @return how many have the same keys

      */

     public static int countObjectsWithIdentitcalKey(Collection<? extends PersistableBusinessObject> collection, PersistableBusinessObject bo) {

         // todo: genericize collectionContainsObjectWithIdentitcalKey() to leverage this method?

         int n = 0;

         for (PersistableBusinessObject item : collection) {

             if (equalByKeys(item, bo)) {

                 n++;

             }

         }

         return n;

     }

     /**

      * Compares a business object with a List of {@link PersistableBusinessObject}s to determine if an object with the same key as the BO exists in the list. If it

      * does, the item is removed from the List. This is functionally similar to List.remove() that operates only on Key values.

      * 

      * @param controlList - The list of items to check

      * @param bo - The BO whose keys we are looking for in the controlList

      */

     public static void removeObjectWithIdentitcalKey(Collection<? extends PersistableBusinessObject> controlList, PersistableBusinessObject bo) {

         for (Iterator<? extends PersistableBusinessObject> i = controlList.iterator(); i.hasNext();) {

                 PersistableBusinessObject listBo = i.next();

             if (equalByKeys(listBo, bo)) {

                 i.remove();

             }

         }

     }

     /**

      * Compares a business object with a List of BOs to determine if an object with the same key as the BO exists in the list. If it

      * does, the item is returned.

      * 

      * @param controlList - The list of items to check

      * @param bo - The BO whose keys we are looking for in the controlList

      */

     public static BusinessObject retrieveObjectWithIdentitcalKey(Collection<? extends PersistableBusinessObject> controlList, PersistableBusinessObject bo) {

         BusinessObject returnBo = null;

         for (Iterator<? extends PersistableBusinessObject> i = controlList.iterator(); i.hasNext();) {

                 PersistableBusinessObject listBo = i.next();

             if (equalByKeys(listBo, bo)) {

                 returnBo = listBo;

             }

         }

         return returnBo;

     }

     /**

      * Determines if a given string could represent a nested attribute of an object.

      * 

      * @param attributeName

      * 

      * @return true if the attribute is nested

      */

     public static boolean isNestedAttribute(String attributeName) {

         boolean isNested = false;

         if (StringUtils.contains(attributeName, ".")) {

             isNested = true;

         }

         return isNested;

     }

     /**

      * Returns the prefix of a nested attribute name, or the empty string if the attribute name is not nested.

      * 

      * @param attributeName

      * 

      * @return everything BEFORE the last "." character in attributeName

      */

     public static String getNestedAttributePrefix(String attributeName) {

         String prefix = "";

         if (StringUtils.contains(attributeName, ".")) {

             prefix = StringUtils.substringBeforeLast(attributeName, ".");

         }

         return prefix;

     }

     /**

      * Returns the primitive part of an attribute name string.

      * 

      * @param attributeName

      * 

      * @return everything AFTER the last "." character in attributeName

      */

     public static String getNestedAttributePrimitive(String attributeName) {

         String primitive = attributeName;

         if (StringUtils.contains(attributeName, ".")) {

             primitive = StringUtils.substringAfterLast(attributeName, ".");

         }

         return primitive;

     }

     /**

      * This method is a OJB Proxy-safe way to test for null on a proxied object that may or may not be materialized yet. It is safe

      * to use on a proxy (materialized or non-materialized) or on a non-proxy (ie, regular object). Note that this will force a

      * materialization of the proxy if the object is a proxy and unmaterialized.

      * 

      * @param object - any object, proxied or not, materialized or not

      * 

      * @return true if the object (or underlying materialized object) is null, false otherwise

      */

     public static boolean isNull(Object object) {

         // regardless, if its null, then its null

         if (object == null) {

             return true;

         }

         // only try to materialize the object to see if its null if this is a

         // proxy object

         if (ProxyHelper.isProxy(object) || ProxyHelper.isCollectionProxy(object)) {

             if (ProxyHelper.getRealObject(object) == null) {

                 return true;

             }

         }

         return false;

     }

     /**

      * This method is a OJB Proxy-safe way to test for notNull on a proxied object that may or may not be materialized yet. It is

      * safe to use on a proxy (materialized or non-materialized) or on a non-proxy (ie, regular object). Note that this will force a

      * materialization of the proxy if the object is a proxy and unmaterialized.

      * 

      * @param object - any object, proxied or not, materialized or not

      * 

      * @return true if the object (or underlying materialized object) is not null, true if its null

      */

     public static boolean isNotNull(Object object) {

         return !ObjectUtils.isNull(object);

     }

     /**

      * This method runs the ObjectUtils.isNotNull() method for each item in a list of BOs. ObjectUtils.isNotNull() will materialize

      * the objects if they are currently OJB proxies.

      * 

      * @param possiblyProxiedObjects - a Collection of objects that may be proxies

      */

     public static void materializeObjects(Collection possiblyProxiedObjects) {

         for (Iterator i = possiblyProxiedObjects.iterator(); i.hasNext();) {

             ObjectUtils.isNotNull(i.next());

         }

     }

     /**

      * This method attempts to materialize all of the proxied reference objects (ie, sub-objects) hanging off the passed-in BO

      * object. It will do it down to the specified depth. An IllegalArgumentException will be thrown if the bo object passed in is

      * itself a non-materialized proxy object. If the bo passed in has no proxied sub-objects, then the object will not be modified,

      * and no errors will be thrown. WARNING: Be careful using depth any greater than 2. The number of DB hits, time, and memory

      * consumed grows exponentially with each additional increment to depth. Make sure you really need that depth before doing so.

      * 

      * @param bo A valid, populated BusinessObject containing (possibly) proxied sub-objects. This object will be modified in place.

      * @param depth int Value 0-5 indicating how deep to recurse the materialization. If a zero (0) is passed in, then no work will

      *        be done.

      */

     public static void materializeSubObjectsToDepth(PersistableBusinessObject bo, int depth) {

         if (bo == null) {

             throw new IllegalArgumentException("The bo passed in was null.");

         }

         if (depth < 0 || depth > 5) {

             throw new IllegalArgumentException("The depth passed in was out of bounds.  Only values " + "between 0 and 5, inclusively, are allowed.");

         }

         // if depth is zero, then we're done recursing and can just exit

         if (depth == 0) {

             return;

         }

         // deal with the possibility that the bo passed in (ie, the parent object) is an un-materialized proxy

         if (ProxyHelper.isProxy(bo)) {

             if (!ProxyHelper.isMaterialized(bo)) {

                 throw new IllegalArgumentException("The bo passed in is an un-materialized proxy, and cannot be used.");

             }

         }

         // get the list of reference objects hanging off the parent BO

         if ( KNSServiceLocator.getPersistenceStructureService().isPersistable( bo.getClass() ) ) {

                 Map<String, Class> references = KNSServiceLocator.getPersistenceStructureService().listReferenceObjectFields(bo);

                 // initialize our in-loop objects

                 String referenceName = "";

                 Class referenceClass = null;

                 Object referenceValue = null;

                 Object realReferenceValue = null;

                 // for each reference object on the parent bo

                 for (Iterator iter = references.keySet().iterator(); iter.hasNext();) {

                     referenceName = (String) iter.next();

                     referenceClass = references.get(referenceName);

                     // if its a proxy, replace it with a non-proxy

                     referenceValue = getPropertyValue(bo, referenceName);

                     if (referenceValue != null) {

                         if (ProxyHelper.isProxy(referenceValue)) {

                             realReferenceValue = ProxyHelper.getRealObject(referenceValue);

                             if (realReferenceValue != null) {

                                 try {

                                     setObjectProperty(bo, referenceName, referenceClass, realReferenceValue);

                                 }

                                 catch (FormatException e) {

                                     throw new RuntimeException("FormatException: could not set the property '" + referenceName + "'.", e);

                                 }

                                 catch (IllegalAccessException e) {

                                     throw new RuntimeException("IllegalAccessException: could not set the property '" + referenceName + "'.", e);

                                 }

                                 catch (InvocationTargetException e) {

                                     throw new RuntimeException("InvocationTargetException: could not set the property '" + referenceName + "'.", e);

                                 }

                                 catch (NoSuchMethodException e) {

                                     throw new RuntimeException("NoSuchMethodException: could not set the property '" + referenceName + "'.", e);

                                 }

                             }

                         }

                         // recurse down through this reference object

                         if (realReferenceValue instanceof PersistableBusinessObject && depth > 1) {

                             materializeSubObjectsToDepth((PersistableBusinessObject) realReferenceValue, depth - 1);

                         }

                     }

                 }

         }

     }

     /**

      * This method attempts to materialize all of the proxied reference objects (ie, sub-objects) hanging off the passed-in BO

      * object. It will do it just three levels down. In other words, it will only materialize the objects that are direct members of

      * the bo, objects that are direct members of those bos, that one more time, and no further down. An IllegalArgumentException 

      * will be thrown if the bo object passed in is itself a non-materialized proxy object. If the bo passed in has no proxied 

      * sub-objects, then the object will not be modified, and no errors will be thrown.

      * 

      * @param bo A valid, populated BusinessObject containing (possibly) proxied sub-objects. This object will be modified in place.

      */

     public static void materializeAllSubObjects(PersistableBusinessObject bo) {

         materializeSubObjectsToDepth(bo, 3);

     }

     /**

      * This method safely extracts either simple values OR nested values. For example, if the bo is SubAccount, and the fieldName is

      * a21SubAccount.subAccountTypeCode, this thing makes sure it gets the value off the very end attribute, no matter how deeply

      * nested it is. The code would be slightly simpler if this was done recursively, but this is safer, and consumes a constant

      * amount of memory, no matter how deeply nested it goes.

      * 

      * @param bo

      * @param fieldName

      * 

      * @return The field value if it exists. If it doesnt, and the name is invalid, and

      */

     public static Object getNestedValue(Object bo, String fieldName) {

         if (bo == null) {

             throw new IllegalArgumentException("The bo passed in was null.");

         }

         if (StringUtils.isBlank(fieldName)) {

             throw new IllegalArgumentException("The fieldName passed in was blank.");

         }

         // okay, this section of code is to handle sub-object values, like

         // SubAccount.a21SubAccount.subAccountTypeCode. it basically walks

         // through the period-delimited list of names, and ends up with the

         // final value.

         String[] fieldNameParts = fieldName.split("\\.");

         Object currentObject = null;

         Object priorObject = bo;

         for (int i = 0; i < fieldNameParts.length; i++) {

             String fieldNamePart = fieldNameParts[i];

             try {

                 if (fieldNamePart.indexOf("]") > 0) {

                     currentObject = PropertyUtils.getIndexedProperty(priorObject, fieldNamePart);

                 }

                 else {

                     currentObject = PropertyUtils.getSimpleProperty(priorObject, fieldNamePart);

                 }

             }

             catch (IllegalAccessException e) {

                 throw new RuntimeException("Caller does not have access to the property accessor method.", e);

             }

             catch (InvocationTargetException e) {

                 throw new RuntimeException("Property accessor method threw an exception.", e);

             }

             catch (NoSuchMethodException e) {

                 throw new RuntimeException("The accessor method requested for this property cannot be found.", e);

             }

             // materialize the proxy, if it is a proxy

             if (ProxyHelper.isProxy(currentObject)) {

                 currentObject = ProxyHelper.getRealObject(currentObject);

             }

             // if a node or the leaf is null, then we're done, there's no need to

             // continue accessing null things

             if (currentObject == null) {

                 return currentObject;

             }

             priorObject = currentObject;

         }

         return currentObject;

     }

     /**

      * Returns the equality of the two given objects, automatically handling when one or both of the objects is null.

      * 

      * @param obj1

      * @param obj2

      * 

      * @return true if both objects are null or both are equal

      */

     public static boolean nullSafeEquals(Object obj1, Object obj2) {

         if (obj1 != null && obj2 != null) {

             return obj1.equals(obj2);

         }

         else {

             return (obj1 == obj2);

         }

     }

     /**

      * This method safely creates a object from a class

      * Convenience method to create new object and throw a runtime exception if it cannot

      * If the class is an {@link ExternalizableBusinessObject}, this method will determine the interface for the EBO and query the

          * appropriate module service to create a new instance.

      * 

      * @param boClass

      * 

      * @return a newInstance() of clazz

      */

     public static Object createNewObjectFromClass(Class clazz) {

                 if (clazz == null) {

                         throw new RuntimeException("BO class was passed in as null");

                 }

                 try {

                         if (ExternalizableBusinessObject.class.isAssignableFrom(clazz)) {

                                 Class eboInterface = ExternalizableBusinessObjectUtils.determineExternalizableBusinessObjectSubInterface(clazz);

                                 ModuleService moduleService = KNSServiceLocator.getKualiModuleService().getResponsibleModuleService(eboInterface);

                                 return moduleService.createNewObjectFromExternalizableClass(eboInterface);

                         }

                         else {

                                 return clazz.newInstance();

                         }

                 } catch (Exception e) {

                         throw new RuntimeException("Error occured while trying to create a new instance for class " + clazz,e);

                 }

     }

         /**

          * Return whether or not an attribute is writeable. This method is aware that that Collections may be involved and handles them

          * consistently with the way in which OJB handles specifying the attributes of elements of a Collection.

          * 

          * @param o

          * @param p

          * @return

          * @throws IllegalArgumentException

          */

         public static boolean isWriteable(Object o, String p, PersistenceStructureService persistenceStructureService)

                         throws IllegalArgumentException {

                 if (null == o || null == p) {

                         throw new IllegalArgumentException("Cannot check writeable status with null arguments.");

                 }

                 boolean b = false;

                 // Try the easy way.

                 if (!(PropertyUtils.isWriteable(o, p))) {

                         // If that fails lets try to be a bit smarter, understanding that Collections may be involved.

                         if (-1 != p.indexOf('.')) {

                                 String[] parts = p.split("\\.");

                                 // Get the type of the attribute.

                                 Class c = ObjectUtils.getPropertyType(o, parts[0], persistenceStructureService);

                                 if (c != null) {

                                         Object i = null;

                                         // If the next level is a Collection, look into the collection, to find out what type its elements are.

                                         if (Collection.class.isAssignableFrom(c)) {

                                                 Map<String, Class> m = persistenceStructureService.listCollectionObjectTypes(o.getClass());

                                                 c = m.get(parts[0]);

                                         }

                                         // Look into the attribute class to see if it is writeable.

                                         try {

                                                 i = c.newInstance();

                                                 StringBuffer sb = new StringBuffer();

                                                 for (int x = 1; x < parts.length; x++) {

                                                         sb.append(1 == x ? "" : ".").append(parts[x]);

                                                 }

                                                 b = isWriteable(i, sb.toString(), persistenceStructureService);

                                         } catch (Exception ex) {

                                                 LOG.error("Skipping Criteria: " + p + " - Unable to instantiate class : " + c.getName(), ex);

                                         }

                                 } else {

                                         LOG.error("Skipping Criteria: " + p + " - Unable to determine class for object: "

                                                         + o.getClass().getName() + " - " + parts[0]);

                                 }

                         }

                 } else {

                         b = true;

                 }

                 return b;

         }

 }