package com.randomnoun.common;

import java.io.IOException;
import java.io.Writer;

/* (c) 2013 randomnoun. All Rights Reserved. This work is licensed under a
 * BSD Simplified License. (http://www.randomnoun.com/bsd-simplified.html)
 */

import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Comparator;
import java.util.Date;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;

import jakarta.servlet.http.HttpServletRequest;

import org.apache.commons.beanutils.PropertyUtils;

import com.randomnoun.common.io.StringBuilderWriter;

/**
 * Encoder/decoder of JavaBeans and 'structured' maps and lists. A structured
 * map or list is any Map or List that satisfies certain conventions, listed below.
 *
 * <p>A structured map is any implementation of the {@link java.util.Map}
 * interface, in which every key is a {@link String}, and every value is either a
 * primitive wrapper type ({@link String}, {@link Long},
 * {@link Integer}, etc...), a structured map or a structured list.
 * A structured list is any implementation of the {@link java.util.List} interface,
 * of which every value is a primitive wrapper type, a structured map or a structured list.
 *
 * <p>In this way, arbitrarily complex objects can be created and passed between
 * Struts code and the business layer, or Struts code and the JSP layer,
 * without resorting to the creation of application-specific
 * datatypes. These datatypes are also used by the Spring JdbcTemplate framework to
 * return values from a database, so it is useful to have some generic functions
 * that operate on them.
 *
 * 
 * @author knoxg
 */
public class Struct {

    /** A ConcurrentReaderHashMap that maps Class objects to Maps, each of which
     *  maps getter method names (e.g. getabcd) to Method objects. Method names should be
     *  lower-cased when elements are added or looked up in this map, to provide
     *  case-insensitivity.
     */
    private static Map<Class<?>, Map<String,Method>> gettersCache;
 
    /** A ConcurrentReaderHashMap that maps Class objects to Maps, each of which
     *  maps setter method names (e.g. setabcd) to Method objects. Method names should be
     *  lower-cased when elements are added or looked up in this map, to provide
     *  case-insensitivity.
     */
    private static Map<Class<?>, Map<String,Method>> settersCache;

    /** Serialise Date objects using the Microsoft convention for Dates, 
     * which is a String in the form <code>"/Date(millisSinceEpoch)/"</code>
     */
        public static final String DATE_FORMAT_MICROSOFT = "microsoft";
        
        /** Serialise Date objects as milliseconds since the epoch */
        public static final String DATE_FORMAT_NUMERIC = "numeric";

        /** This class can be serialised as a JSON value by calling it's toString() method */ 
        public static interface ToStringReturnsJson { }
        
        /** This class can be serialised as a JSON value by calling it's toJson() method */
        public static interface ToJson { 
                public String toJson(); 
        }
        
        /** This class can be serialised as a JSON value by calling it's toJson(String) method. 
     * Multiple json formats are supported by supplying a jsonFormat string; e.g. 'simple'. 
     * Passing null or an empty string should be equivalent to calling toJson() if the class also implements the Struct.ToJson interface.
     */
        public static interface ToJsonFormat { 
                public String toJson(String jsonFormat); 
        }
        
        /** This class can be serialised as a JSON value by calling it's writeJsonFormat() method 
     * Multiple json formats are supported by supplying a jsonFormat string; e.g. 'simple'. 
     * Passing null or an empty string should be equivalent to calling toJson() if the class also implements the Struct.ToJson interface.
         */
        public static interface WriteJsonFormat { 
                public void writeJsonFormat(Writer w, String jsonFormat) throws IOException; 
        }
        
        // @TODO when we move to jdk 11 layer extend these interfaces over each other with default implementations, + filteredJson interface
        
        /** A comparator that allows elements within lists to be sorted, allowing
         * nulls (in order to sort map keys)
         */
    static class ListComparator implements Comparator
    {
        public int compare(Object o1, Object o2) {
            if (o1 == null && o2 == null) {
                return 0;
            } else if (o1 == null) {
                return -1;
            } else if (o2 == null) {
                return 1;
            }
            return ((Comparable)o1).compareTo(o2);
        }
    }
    
    /** Backwards compatible class until this is removed */
    public static class ListContainingNullComparator extends ListComparator { };
    
    
    /** A Comparator which performs comparisons between two rows in a structured list (used
     *  in sorting). This comparator is equivalent to an 'ORDER BY' on a single field
     *  returned by the Spring JdbcTemplate method.
     */
    public static class StructuredListComparator implements Comparator {
        /** The key field to sort on */
        private String fieldName;

        /** Create a new StructuredListComparator object, which will sort on the
         *  supplied field.
         *
         * @param fieldName The name of the field to sort on
         */
        public StructuredListComparator(String fieldName) {
            this.fieldName = fieldName;
        }

        /** Compare two structured list elements
         *
         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
         */
        public int compare(Object a, Object b)
            throws IllegalArgumentException {
            if (!(a instanceof Map)) {
                throw new IllegalArgumentException("List must be composed of Maps");
            }
            if (!(b instanceof Map)) {
                throw new IllegalArgumentException("List must be composed of Maps");
            }

            Map mapA = (Map) a;
            Map mapB = (Map) b;
            if (!mapA.containsKey(fieldName)) {
                throw new IllegalArgumentException("keyField '" + fieldName + "' not found in Map");
            }
            if (!mapB.containsKey(fieldName)) {
                throw new IllegalArgumentException("keyField '" + fieldName + "' not found in Map");
            }

            Object objectA = mapA.get(fieldName);
            if (!(objectA instanceof Comparable)) {
                throw new IllegalArgumentException("keyField '" + fieldName + "' element must implement Comparable");
            }
            return ((Comparable) objectA).compareTo(mapB.get(fieldName));
        }
    }


    /** A Comparator which performs comparisons between two rows in a structured list (used
     *  in sorting), keyed on a case-insensitive String value. This comparator is similar to an 
     * 'ORDER BY' on a single field returned by the Spring JdbcTemplate method.
     */
    public static class StructuredListComparatorIgnoreCase implements Comparator {

        /** The key field to sort on */
        private String fieldName;

        /** Create a new StructuredListComparatorIgnoreCase object, which will sort on the
         *  supplied field.
         *
         * @param fieldName The name of the field to sort on
         */
        public StructuredListComparatorIgnoreCase(String fieldName) {
            this.fieldName = fieldName;
        }

        /** Compare two structured list elements
         *
         * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
         */
        public int compare(Object a, Object b)
            throws IllegalArgumentException {
            if (!(a instanceof Map)) {
                throw new IllegalArgumentException("List must be composed of Maps");
            }
            if (!(b instanceof Map)) {
                throw new IllegalArgumentException("List must be composed of Maps");
            }

            Map mapA = (Map) a;
            Map mapB = (Map) b;
            if (!mapA.containsKey(fieldName)) {
                throw new IllegalArgumentException("keyField '" + fieldName + "' not found in Map");
            }
            if (!mapB.containsKey(fieldName)) {
                throw new IllegalArgumentException("keyField '" + fieldName + "' not found in Map");
            }

            String stringA = (String) mapA.get(fieldName);
            return stringA.compareToIgnoreCase((String) mapB.get(fieldName));
        }
    }


    /** Sorts a structured list on the supplied key field
     *
     * @param list The list to search.
     * @param keyField The name of the key field.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalStateException if the list is not composed of Maps
     */
    static public void sortStructuredList(List list, String keyField) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }

        Comparator comparator = new StructuredListComparator(keyField);
        Collections.sort(list, comparator);
    }

    /** Sorts a structured list on the supplied key field; the key value is sorted
     * case-insensitively (it must be of type String or a ClassCastException will occur).
     *
     * @param list The list to search.
     * @param keyField The name of the key field.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalStateException if the list is not composed of Maps
     */
    static public void sortStructuredListIgnoreCase(List list, String keyField) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }

        Comparator comparator = new StructuredListComparatorIgnoreCase(keyField);
        Collections.sort(list, comparator);
    }


    /** Set all fields in object 'obj' using values in request. Each request parameter
     *  is checked against the object to see if a bean setter method exists for that
     *  parameter name. If it does, then it is invoked, using the parameter value
     *  as the setter argument. This method uses the
     * {@link Struct#setValue(Object, String, Object, boolean, boolean, boolean)} method
     *  to dynamically create map and list elements as required if the object being
     *  set implements the Map interface.
     *
     *  <p>e.g. if passed a Map object, and the HttpServletRequest has a parameter named
     *  "<code>table[12].id</code>" with the value "<code>1234</code>", then:
     *  <ul><li>a List object named "table" is created
     *  in the Map,
     *  <li>the list is increased to allow at least 12 elements,
     *  <li> that element is set to a new Map object ...
     *  <li> ... which contains the String key "id", which is assigned the  value "1234".
     *  </ul>
     *  <p>This processing allows developers to pass arbitrarily complex structures through
     *  from HttpServletRequest name/value pairs.
     *
     *  <p>This method operates on both structured objects (Maps/Lists) or 
     *  data-transfer objects (DTOs). For example, if passed a bean-like Object which had a getTable() method that
     *  returned a List, then this would be used to perform the processing above. (If the
     *  List returned a Map at index 12, then an 'id' key would be created as before; if
     *  the List returned another Object at index 12, then the setId() method would be
     *  called instead; if the list returned null at index 12, then a Map would be created as before).
     *
     *  <p>NB: If an object is not a Map, and does not have the appropriate setter() method,
     *  then this function will *not* raise an exception. This is intentional behaviour -
     *  (use {@link #setValue(Object, String, Object, boolean, boolean, boolean)} if you
     *  need more fine-grained control.
     *
     *  <p>You can limit the setters that are invoked by using the
     *  {@link #setFromRequest(Object, HttpServletRequest, String[])} form of this method.
     *
     * @param obj The object being set.
     * @param request The request containing the source data
     *
     * @throws RuntimeException if an invocation target exception occurred whilst
     *   calling the object's set() methods.
     */
    public static void setFromRequest(Object obj, HttpServletRequest request) {
        setFromRequest(obj, request, null);
    }

    /** Set all fields in object 'obj' using values in request. Only the request
     *  parameter names passed in through the 'fields' argument will be used
     *  to populate the object. If the named parameter does not exist in the request,
     *  then the setter for that parameter is not invoked.
     *
     *  <p>See {@link #setFromRequest(Object, HttpServletRequest)} for more information
     *  on how this method operates.
     *
     * @param obj The object being set.
     * @param request The request containing the source data
     * @param fields An array of strings, denoting the fields that are sourced from
     *   the request. All other parameters in the request are ignored.
     *
     * @throws RuntimeException if an invocation target exception occurred whilst
     *   calling the object's set() methods.
     */
    public static void setFromRequest(Object obj, HttpServletRequest request, String[] fields) {
        Iterator paramListIter;

        if (fields == null) {
            paramListIter = request.getParameterMap().keySet().iterator();
        } else {
            paramListIter = Arrays.asList(fields).iterator();
        }

        while (paramListIter.hasNext()) {
            String parameter = (String) paramListIter.next();
            if (parameter.endsWith("[]")) {
                parameter = parameter.substring(0, parameter.length()-2);
                String values[] = request.getParameterValues(parameter);
                if (values!=null) {
                        for (int i=0; i<values.length; i++) {
                                values[i] = Text.replaceString(values[i], "\015\012", "\n");
                        }
                }
                setValue(obj, parameter, values, true, true, true);
            } else {
                    String value = request.getParameter(parameter);
                    
                    // convert CR-LFs into java newlines 
                    value = Text.replaceString(value, "\015\012", "\n");
        
                    // The null check below is commented out because we need to be able to pass
                    // null values through in order to set booleans values for checkboxes
                    // that are unchecked (these are represented in HTTP by missing (null) parameters)
        
                    //if (value != null) { 
                    setValue(obj, parameter, value, true, true, true);
                    //}
            }
        }
    }


    /** Similar to the {@link #setFromRequest(Object, HttpServletRequest)} method, but
     *  uses a Map instead of a request.
     * 
     * @param obj The object being set.
     * @param map The Map containing the source data
     * @param ignoreMissingSetter passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)} 
     * @param convertStrings passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     * @param createMissingElements passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     */
    public static void setFromMap(Object obj, Map map, 
      boolean ignoreMissingSetter, boolean convertStrings, boolean createMissingElements) 
    {
        setFromMap(obj, map, ignoreMissingSetter, convertStrings, createMissingElements, null); 
    }

    /** Similar to the {@link #setFromRequest(Object, HttpServletRequest, String[])} method, but
     *  uses a Map instead of a request.
     * 
     * @param obj The object being set.
     * @param map The Map containing the source data
     * @param ignoreMissingSetter passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)} 
     * @param convertStrings passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     * @param createMissingElements passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     * @param fields An array of strings, denoting the fields that are sourced from
     *   the request. All other parameters in the request are ignored.
     */
    public static void setFromMap(Object obj, Map map, 
      boolean ignoreMissingSetter, boolean convertStrings, boolean createMissingElements, 
      String[] fields) 
    {
        if (fields == null) {
            for (Iterator<?> i = map.entrySet().iterator(); i.hasNext(); ) {
                Map.Entry<?, ?> entry = (Map.Entry<?, ?>) i.next();
                setValue(obj, (String) entry.getKey(), entry.getValue(), ignoreMissingSetter, convertStrings, createMissingElements);
            }
        } else {
            for (int i = 0; i<fields.length; i++) {
                setValue(obj, fields[i], map.get(fields[i]), ignoreMissingSetter, convertStrings, createMissingElements);
            }
        }
    }

    /** Similar to the {@link #setFromRequest(Object, HttpServletRequest, String[])} method, but
     *  uses a Map instead of a request.
     * 
     * @param targetObj The object being set.
     * @param sourceObj The Map containing the source data
     * @param ignoreMissingSetter passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)} 
     * @param convertStrings passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     * @param createMissingElements passed to {@link #setValue(Object, String, Object, boolean, boolean, boolean)}
     * @param fields An array of strings, denoting the fields that are sourced from
     *   the request. All other parameters in the request are ignored.
     */
    public static void setFromObject(Object targetObj, Object sourceObj, 
      boolean ignoreMissingSetter, boolean convertStrings, boolean createMissingElements, 
      String[] fields) 
    {
        // probably something in bean-utils for all of this
        if (fields == null) {
                /*
            for (Iterator i = sourceObj.entrySet().iterator(); i.hasNext(); ) {
                Map.Entry entry = (Map.Entry) i.next();
                setValue(targetObj, (String) entry.getKey(), entry.getValue(), ignoreMissingSetter, convertStrings, createMissingElements);
            }
            */
                throw new UnsupportedOperationException("null field list not supported");
        } else {
            for (int i = 0; i<fields.length; i++) {
                setValue(targetObj, fields[i], getValue(sourceObj, fields[i]), ignoreMissingSetter, convertStrings, createMissingElements);
            }
        }
    }
    
    

    /** Return a getter Method for a class. 
     *
     * <p>(Getters are cached by this class)
     *
     * @param clazz The class we are retrieving the getter Method for
     * @param propertyName The name of the property on this class; e.g. "asd" will return the
     *   method "getAsd()"
     * 
     * @return the getter Method for the supplied class.
     */
    private static Method getGetterMethod(Class<?> clazz, String propertyName) {
        Map<String,Method> getters = (Map<String,Method>) gettersCache.get(clazz);

        if (getters == null) {
            getters = new HashMap<String,Method>();

            Method[] methods = clazz.getMethods();
            Method method;

            // get a list of setters this object contains
            for (int i = 0; i < methods.length; i++) {
                method = methods[i];

                if (method.getName().startsWith("get") && method.getParameterTypes().length == 1) {
                    String property = method.getName().substring(3);
                    getters.put(property.toLowerCase(), method);
                }
            }
            gettersCache.put(clazz, getters);
        }

        return (Method) getters.get(propertyName.toLowerCase());
    }

    /** Return a setter method for a class. Note that if a class supplies multiple setters (with
     * one parameter each), then one will be arbitrarily chosen. So don't have multiple setters ! 
     *
     * <p>(Setters are cached by this class)
     *
     * @param clazz The class we are retrieving the setter Method for
     * @param propertyName The name of the property on this class; e.g. "asd" will return the
     *   first "setAsd(...)" found on this class with one parameter.
     * 
     * @return The setter Method for the supplied class
     */
    private static Method getSetterMethod(Class<?> clazz, String propertyName) {
        Map<String,Method> setters = (Map<String, Method>) settersCache.get(clazz);

        if (setters == null) {
            setters = new HashMap<String,Method>();

            Method[] methods = clazz.getMethods();
            Method method;

            // get a list of setters this object contains
            for (int i = 0; i < methods.length; i++) {
                method = methods[i];

                if (method.getName().startsWith("set") && method.getParameterTypes().length == 1) {
                    String property = method.getName().substring(3);
                    setters.put(property.toLowerCase(), method);
                }
            }
            settersCache.put(clazz, setters);
        }

        return (Method) setters.get(propertyName.toLowerCase());
    }

    /** Call setter method, converting from String */
    private static void callSetterMethodWithString(Object target, Method setter, String value) {
        Class<?> clazz = setter.getParameterTypes()[0];
        Object realValue;

        if (clazz.equals(String.class)) {
            realValue = value;
        } else if (clazz.equals(boolean.class)) {
            realValue = Boolean.valueOf(value);
        } else if (clazz.equals(long.class)) {
                realValue = value.equals("") ? new Long(0) : new Long(value);
        } else if (clazz.equals(int.class)) {
                realValue = value.equals("") ? new Integer(0) : new Integer(value);
        } else if (clazz.equals(double.class)) {
                realValue = value.equals("") ? new Double(0) : new Double(value);
        } else if (clazz.equals(float.class)) {
                realValue = value.equals("") ? new Float(0) : new Float(value);
        } else if (clazz.equals(short.class)) {
                realValue = value.equals("") ? new Short((short) 0) : new Short(value);
        // missing char.class here

        } else if (clazz.equals(Long.class)) {
                realValue = value.equals("") ? null : new Long(value);
        } else if (clazz.equals(Integer.class)) {
                realValue = value.equals("") ? null : new Integer(value);
        } else if (clazz.equals(Double.class)) {
                realValue = value.equals("") ? null : new Double(value);
        } else if (clazz.equals(Float.class)) {
                realValue = value.equals("") ? null : new Float(value);
        } else if (clazz.equals(Short.class)) {
                realValue = value.equals("") ? null : new Short(value);
        // missing Character.class here
        
        
        } else {
            throw new IllegalArgumentException("Cannot convert string value to " + "'" + clazz.getName() + "' required for setter method '" + setter.getName() + "'");
        }

        callSetterMethod(target, setter, realValue);
    }

    /** Call getter method */
    private static Object callGetterMethod(Object target, Method getter) {
        Object[] methodArgs = new Object[0];

        try {
            return getter.invoke(target, methodArgs);
        } catch (InvocationTargetException ite) {
            // if (ite instanceof RuntimeException) { throw ite; }
            throw (IllegalArgumentException) new IllegalArgumentException("Exception calling method '" + getter.getName() + "' on object '" + target.getClass().getName() + "': " + ite.getMessage()).initCause(ite);
        } catch (IllegalAccessException iae) {
            throw (IllegalArgumentException) new IllegalArgumentException("Exception calling method '" + getter.getName() + "' on object '" + target.getClass().getName() + "': " + iae.getMessage()).initCause(iae);
        }
    }

    /** Checks whether the an instance of the value class can be assigned to a variable
     * of 'variableClass' class via a
     * {@see java.lang.reflect.Method#invoke(java.lang.Object, java.lang.Object[])}
     * method. This is different to the normal
     * {@see java.lang.Class#isAssignableFrom(java.lang.Class)} method since it
     * also takes primitive to wrapper conversions into account.
     *
     * @param variableClass The class representing the variable we are assigning to
     *   (e.g. the 'x' in 'x = y')
     * @param value The class representing the value we are assigning to the variable
     *   (e.g. the 'y' in 'x = y')
     *
     * @return true if the assignment is compatible, false otherwise.
     */
    private static boolean isAssignmentSafe(Class variableClass, Class value) {
        // check for instance or wrapper type
        return variableClass.isAssignableFrom(value) || 
          (variableClass.equals(boolean.class) && value.equals(Boolean.class)) || 
          (variableClass.equals(char.class) && value.equals(Character.class)) || 
          (variableClass.equals(byte.class) && value.equals(Byte.class)) || 
          (variableClass.equals(short.class) && value.equals(Short.class)) || 
          (variableClass.equals(int.class) && value.equals(Integer.class)) || 
          (variableClass.equals(long.class) && value.equals(Long.class)) || 
          (variableClass.equals(float.class) && value.equals(Float.class)) || 
          (variableClass.equals(double.class) && value.equals(Double.class));
    }

    /** Call setter method */
    private static void callSetterMethod(Object target, Method setter, Object value) {

        Object[] methodArgs = new Object[1];
        methodArgs[0] = value;
        
        if (value!=null) {
                Class<?> setterParamClass = setter.getParameterTypes()[0];
                Class<?> valueClass = value.getClass();
                
                // special case for assigning Numbers (including BigDecimals) to longs
                        if (setterParamClass.equals(Long.class) && Number.class.isAssignableFrom(valueClass)) { // valueClass.equals(BigDecimal.class)
                                methodArgs[0] = new Long(((Number)value).longValue()); 
                        } else if (setterParamClass.equals(long.class) && Number.class.isAssignableFrom(valueClass)) { // valueClass.equals(BigDecimal.class)
                        methodArgs[0] = new Long(((Number)value).longValue()); 
                } else {
                        if (!isAssignmentSafe(setterParamClass, value.getClass())) {
                                // see if we can shoe-horn it in
                                
                                
                            throw new IllegalArgumentException("Exception calling method '" + setter.getName() + 
                                          "' on object '" + target.getClass().getName() + "': value object of type '" + 
                                          valueClass.getName() + "' is not assignment-compatible with setter parameter '" + 
                                          setterParamClass.getName() + "'");
                        }
                }
        }

        try {
            setter.invoke(target, methodArgs);
        } catch (InvocationTargetException ite) {
            // if (ite instanceof RuntimeException) { throw ite; }
            throw (IllegalArgumentException) new IllegalArgumentException("Exception calling method '" + setter.getName() + "' on object '" + target.getClass().getName() + "': " + ite.getMessage()).initCause(ite);
        } catch (IllegalAccessException iae) {
            throw (IllegalArgumentException) new IllegalArgumentException("Exception calling method '" + setter.getName() + "' on object '" + target.getClass().getName() + "': " + iae.getMessage()).initCause(iae);
        } catch (Exception e) {
            // if (ite instanceof RuntimeException) { throw ite; }
            throw (IllegalArgumentException) new IllegalArgumentException("Exception calling method '" + setter.getName() + "' on object '" + target.getClass().getName() + "': " + e.getMessage()).initCause(e);
        }
    }


    /** Return a single value from a structured map. Returns null if the
     *  value does not exist, or if an error occurred retrieving it.
     *
     * @param object The structure map
     * @param key The key of the value we wish to retrieve (e.g. "abc.def[12].ghi")
     *
     * @return The value
     */
    static public Object getValue(Object object, String key) {
        // @TODO (low priority) make this function consistent with setValue()
        // the PropertyUtils object below is taken from Jakarta's commons-beanutils.jar 
        // package, which has similar, but not identical semantics. 
        // The provided functionality should hopefully be a superset of that
        // provided by this class anyway, so it may not be important. 
        // (beanutils property retrieval allows curly-brace "{"/"}"-style syntax
        // which we don't allow here).

        try {
            return PropertyUtils.getProperty(object, key);
        } catch (Exception e) {
            return null;
        }
    }

    /** Sets a single value in a structured object. The object may be composed
     * of javabean-style objects, Map/List classes, or a combination of the two.
     * 
     * <p>There is a possible denial-of-service attack that can be used against
     * this method which you should probably be aware of, but can't do anything about:
     * if a large list index is supplied, e.g. "<code>abc[1293921]</code>", then a list will be
     * generated with this many elements in it. There are workarounds for this, 
     * but none are really satisfactory.
     * 
     * <p>It should also be noted that even if an exception is thrown within this
     * method, the data structure underneath it may still have been modified, e.g.
     * setting "<code>abc.def.ghi</code>" may successfully construct 'def' but later
     * fail on 'ghi'. 
     * 
     * @param object The structure map or list
     * @param key The key of the value we wish to set (e.g. "abc.def[12].ghi"). Note
     *   that map keys are assumed; i.e. they are not enclosed in 'curly braces'.
     * @param value The value to set this to
     * @param ignoreMissingSetter If we are asked to set a value in an object which
     *   does not have an appropriate setter, don't raise an exception (just does
     *   nothing instead).
     * @param convertStrings If we are asked to set a string value in an object
     *   which has a setter, but of a different type (e.g. setCustomerId(Long)),
     *   performs conversions to that type automatically. (Useful when setting
     *   values sourced from a HttpServletRequest, which will always be of String type).
     * @param createMissingElements If we are asked to set a value in a Map or List
     *   that does not exist, will create the required Map keys or extend the List
     *   so that the value can be set.
     *
     * @throws IllegalArgumentException if
     * <ul><li>An null map or list is navigated down
     * <li>A non-List object is invoked with the '[]' operator
     * <li>A non-Map object is invoked with the '.' operator, or the object
     *   has no getter/setter method with the appropriate name
     * <li>An empty mapped property is supplied e.g. bob..something
     * <li>An invalid key was supplied (e.g. 'bob[123' -- no closing square bracket)
     * </ul>
     * @throws NumberFormatException if an array index cannot be converted to
     *   an integer via {@link java.lang.Integer#parseInt(java.lang.String)}.
     */
    static public void setValue(Object object, String key, Object value, boolean ignoreMissingSetter, boolean convertStrings, boolean createMissingElements)
        throws NumberFormatException 
    {
        if (object == null) { throw new NullPointerException("null object"); }
        if (key == null) { throw new NullPointerException("null key"); }

        // parse state: 
        //   0=searching for new value (at start of line) 
        //   1=consuming list index (after '[')
        //   2=consuming map index (after start of line or after '.')
        //   3=search for new value (after ']')
        Object ref = object; // reference into object

        int parseState = 0;
        int length = key.length();
        String element;
        int elementInt = -1;
        List lastList = null;
        String parentName = null;
        Object parentRef = null;
        
        if (object instanceof List) { lastList = (List) object; }

        char ch;
        StringBuffer buffer = new StringBuffer();

        for (int pos = 0; pos < length; pos++) {
            ch = key.charAt(pos);

            // System.out.println("pos " + pos + ", state=" + parseState + ", nextchar=" + ch + ", buf=" + buffer);
            switch (parseState) {
                
                case 0: 
                    if (ch == '[') {
                        buffer.setLength(0);
                        parseState = 1;
                    } else { // could check for legal map index characters here
                        buffer.setLength(0);
                        buffer.append(ch);
                        parseState = 2;
                    }
                    break;
                    
                case 3:
                    if (ch == '[') {
                        buffer.setLength(0);
                        parseState = 1;
                    } else if (ch == '.') {
                        buffer.setLength(0);
                        parseState = 2;
                    } else {
                        throw new IllegalArgumentException("Expecting '[' or '.' after ']' in key '" + key + "'; found '" + ch + "'");
                    }
                    break;
                
                case 1:
                    if (ch >= '0' && ch <= '9') {
                        buffer.append(ch);
                    } else if (ch == ']') {
                        element = buffer.toString();
                        elementInt = Integer.parseInt(element);

                        if (ref == null) {
                            // create list if parent was a map
                            if ((parentRef instanceof Map) && createMissingElements) {
                                ref = new ArrayList();
                                ((Map) parentRef).put(parentName, ref);
                            } else if ((parentRef instanceof List) && createMissingElements) {
                                ref = new ArrayList();
                                ((List) parentRef).set(Integer.parseInt(parentName), ref);
                            } else {
                                throw new IllegalArgumentException("Could not retrieve indexed property " + element + " in key '" + key + "' from null object");
                            }
                        }

                        if (ref instanceof List) {
                            lastList = (List) ref;

                            // XXX: denial of service attacks possible here
                            // (large list number may exceed available memory)
                            if (lastList.size() <= elementInt) {
                                setListElement(lastList, elementInt, null);
                            }

                            parentName = element;
                            parentRef = ref;
                            ref = lastList.get(elementInt);
                        } else {
                            // could attempt to reflect on a get(int)-style method,
                            // but this seems like overkill; anything that has List-like
                            // semantics should implement the List interface.
                            throw new IllegalArgumentException("Could not retrieve indexed property " + element + " in key '" + key + "' from object of type '" + ref.getClass().getName() + "'");
                        }

                        parseState = 3;
                    } else {
                        throw new IllegalArgumentException("Illegal character '" + ch + "'" + " found in list index");
                    }
                    break;
                
                case 2:
                    if (ch != '.' && ch != '[') {
                        buffer.append(ch);
                    } else {
                        // navigate map
                        element = buffer.toString();

                        if (ref == null) {
                            if ((parentRef instanceof List) && createMissingElements) {
                                ref = new HashMap();
                                ((List) parentRef).set(Integer.parseInt(parentName), ref);
                            } else if ((parentRef instanceof Map) && createMissingElements) {
                                ref = new HashMap();
                                ((Map) parentRef).put(parentName, ref);
                            } else {
                                throw new IllegalArgumentException("Could not retrieve mapped property '" + element + "' in key '" + key + "' from null object");
                            }
                        }

                        if (element.equals("")) {
                            throw new IllegalArgumentException("Could not retrieve empty mapped property '" + element + "' in key '" + key + "'");
                        } else if (ref instanceof Map) {
                            parentName = element;
                            parentRef = ref;
                            ref = ((Map) ref).get(element);
                        } else {
                            // look for getter method
                            Method getter = getGetterMethod(ref.getClass(), element);

                            if (getter == null) {
                                throw new IllegalArgumentException("Could not retrieve mapped property '" + element + "' in key '" + key + "' for class '" + ref.getClass().getName() + "': no getter method found");
                            }

                            parentName = null; // can't dynamically create these
                            parentRef = null;
                            ref = callGetterMethod(ref, getter);
                        }

                        buffer.setLength(0);

                        if (ch == '[') {
                            parseState = 1;
                        } else if (ch == '.') {
                            parseState = 2;
                        } else {
                            throw new IllegalStateException("Unexpected character '" + ch + "' parsing key '" + key + "'");
                        }
                    }
                    break;
                
                default:
                    throw new IllegalStateException("Unexpected state " + parseState + " parsing key '" + key + "'");
            }
        }

        if (parseState == 0) {
            throw new IllegalStateException("Unexpected error after parsing key '" + key + "'");
        } else if (parseState == 1) {
            throw new IllegalStateException("Missing ']' in key '" + key + "'");
        } else if (parseState == 2) {
            // set mapped property
            element = buffer.toString();

            if (ref == null) {
                if ((parentRef instanceof Map) && createMissingElements) {
                    ref = new HashMap();
                    ((Map) parentRef).put(parentName, ref);
                } else if ((parentRef instanceof List) && createMissingElements) {
                    ref = new HashMap();
                    ((List) parentRef).set(Integer.parseInt(parentName), ref);
                } else {
                    throw new IllegalArgumentException("Could not set mapped property '" + element + "' in key '" + key + "' for null object");
                }
            }

            if (element.equals("")) {
                throw new IllegalArgumentException("Could not set empty mapped property '" + element + "' in key '" + key + "'");
            } else if (ref instanceof Map) {
                ((Map) ref).put(element, value);
            } else {
                Method setter = getSetterMethod(ref.getClass(), element);

                if (setter == null) {
                    // System.out.println("Missing setter '" + element + "'");
                    if (!ignoreMissingSetter) {
                        throw new IllegalArgumentException("Could not set mapped property '" + element + "' in key '" + key + "' for class '" + ref.getClass().getName() + "': no setter method found");
                    }
                } else {
                    // System.out.println("Setting '" + element + "' with value " + value);
                    try {
                            if (convertStrings && ((value == null) || (value instanceof String))) {
                                if (value==null) { value = ""; }
                                callSetterMethodWithString(ref, setter, (String) value);
                            } else {
                                callSetterMethod(ref, setter, value);
                            }
                    } catch (Exception e) {
                        throw (IllegalArgumentException) new IllegalArgumentException("Could not set field '" + key + "' with value '" + value + "'").initCause(e);
                    }
                }
            }
        } else if (parseState == 3) {
            // set list property
            // ref currently points to the current list element; we want to set the 
            // value of the last list we saw, contained in lastList.
            ref = lastList;

            if (ref == null) {
                throw new IllegalArgumentException("Could not set indexed property '" + elementInt + "' in key '" + key + "' for null object");
            }

            if (ref instanceof List) {
                ((List) ref).set(elementInt, value);
            } else {
                throw new IllegalArgumentException("Could not set indexed property " + elementInt + " in key '" + key + "' in object of type '" + ref.getClass().getName() + "'");
            }
        }
    }

    /** Sets the element at a particular list index to a particular object.
     * This differs from the standard List.set() method inasmuch as the list
     * is allowed to grow in the case where index&gt;=List.size(). If the list
     * needs to grow to accomodate the new element, then null objects are
     * appended until the list is large enough.
     *
     * @param list   The list to modify
     * @param index  The position within the list we wish to set to this object
     * @param object The object to be placed into the list.
     */
    public static void setListElement(List list, int index, Object object) {
        int size;

        if (list == null) {
            throw new NullPointerException("list parameter must not be null");
        }

        if (index < 0) {
            throw new IndexOutOfBoundsException("index parameter must be >= 0");
        }

        size = list.size();

        while (index >= size) {
            list.add(null);
            size = size + 1;
        }

        list.set(index, object);
    }

    /** As per {@link #getStructuredListItem(List, String, Object)}, with a 
     * numeric key.
     * 
     * @param list The list to search.
     * @param keyField The name of the key field.
     * @param longValue The key value to search for
     *
     * @return The requested element in the list, or null if the element cannot be found.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalStateException if the list is not composed of Maps
     */
    static public Map getStructuredListItem(List list, String keyField, long longValue) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }

        Map row;
        Object foundKey;
        for (Iterator i = list.iterator(); i.hasNext();) {
            try {
                row = (Map) i.next();
            } catch (ClassCastException cce) {
                throw (IllegalStateException) new IllegalStateException("List must be composed of Maps").initCause(cce);
            }
            foundKey = row.get(keyField);
            if (foundKey != null) {
                if (!(foundKey instanceof Number)) {
                    throw (IllegalStateException) new IllegalStateException("Key is not numeric (found '" + foundKey.getClass().getName() + "' instead)");
                }
                if (((Number) foundKey).longValue() == longValue) {
                    return row;
                }
            }
        }
        return null;
    }

    /** As per {@link #getStructuredListObject(List, String, Object)}, with a 
     * numeric key.
     *
     * @param list The list to search.
     * @param keyField The name of the key field.
     * @param longValue The key value to search for
     *
     * @return The requested element in the list, or null if the element cannot be found.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalStateException if the list is not composed of Maps
     */
    static public Object getStructuredListObject(List list, String keyField, long longValue) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }
        Object row;
        Object foundKey;
        for (Iterator i = list.iterator(); i.hasNext();) {
            row = i.next();
            foundKey = Struct.getValue(row, keyField); 
            if (foundKey != null) {
                if (!(foundKey instanceof Number)) {
                    throw (IllegalStateException) new IllegalStateException("Key is not numeric (found '" + foundKey.getClass().getName() + "' instead)");
                }
                if (((Number) foundKey).longValue() == longValue) {
                    return row;
                }
            }
        }
        return null;
    }

    
    /** Searches a structured list for a particular row. The list is presumed to be a List of Maps,
     *  each of which contains a key field. Lists are searched sequentially until the desired row is
     *  found. It is permitted to search on null key values. If the row cannot be found, null is
     *  returned.
     *
     *  <p>For example, in the list:
     *  <pre>
     *  list = [
     *    0: { systemId = "abc", systemTimezone = "dalby" }
     *    1: { systemId = "def", systemTimezone = "london" }
     *    2: { systemId = "ghi", systemTimezone = "new york" }
     *  ]
     *  </pre>
     *
     *  <p><code>getStructuredListItem(list, "systemId", "def")</code> would return a reference to the
     *  second element in the list, i.e. the Map:
     *
     *  <pre>
     *  { systemId = "def", systemTimezone = "london" }
     *  </pre>
     *
     * @param list The list to search.
     * @param keyField The name of the key field.
     * @param key The key value to search for
     *
     * @return The requested element in the list, or null if the element cannot be found.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalArgumentException if the list is not composed of Maps
     */
    static public Map getStructuredListItem(List list, String keyField, Object key) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }
        Map row;
        Object foundKey;
        for (Iterator i = list.iterator(); i.hasNext();) {
            // could handle generic objects via Codec.getValue(row, keyField); instead
            try {
                row = (Map) i.next();
            } catch (ClassCastException cce) {
                throw (IllegalArgumentException) new IllegalArgumentException("List must be composed of Maps").initCause(cce);
            }
            foundKey = row.get(keyField);  
            if (foundKey == null && key==null) {
                return row;
            } else {
                if (foundKey!=null && foundKey.equals(key)) {
                    return row;
                }
            }
        }
        return null;
    }
    
        // fun fun fun
         /** As per {@link Struct#getStructuredListItem(List, String, long)}, with a 
    * compound key.
    * 
    * @param list The list to search.
    * @param keyField The name of the key field.
    * @param longValue The key value to search for
    * @param keyField2 The name of the second key field.
    * @param longValue2 The second key value to search for
    *
    * @return The requested element in the list, or null if the element cannot be found.
    *
    * @throws NullPointerException if list or keyField is set to null.
    * @throws IllegalStateException if the list is not composed of Maps
    */
   static public Map getStructuredListItem2(List list, String keyField, long longValue, String keyField2, long longValue2) {
       if (list == null) { throw new NullPointerException("Cannot search null list"); }
       if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }
       if (keyField2 == null) { throw new NullPointerException("Cannot search for null keyField2"); }

       Map row;
       Object foundKey, foundKey2;
       for (Iterator i = list.iterator(); i.hasNext();) {
           try {
               row = (Map) i.next();
           } catch (ClassCastException cce) {
               throw (IllegalStateException) new IllegalStateException("List must be composed of Maps").initCause(cce);
           }
           foundKey = row.get(keyField);
           if (foundKey != null) {
               if (!(foundKey instanceof Number)) {
                   throw (IllegalStateException) new IllegalStateException("Key is not numeric (found '" + foundKey.getClass().getName() + "' instead)");
               }
               if (((Number) foundKey).longValue() == longValue) {
                
                foundKey2 = row.get(keyField2);
                if (foundKey2 != null) {
                       if (!(foundKey2 instanceof Number)) {
                           throw (IllegalStateException) new IllegalStateException("Key2 is not numeric (found '" + foundKey2.getClass().getName() + "' instead)");
                       }
                }
                   if (((Number) foundKey2).longValue() == longValue2) {
                        return row;
                   }
               }
           }
       }
       return null;
   }
   
   


    /** Searches a structured list for a particular row. The list may
     * be composed of arbitrary objects.
     *
     * @param list The list to search.
     * @param keyField The name of the key field.
     * @param key The key value to search for
     *
     * @return The requested element in the list, or null if the element cannot be found.
     *
     * @throws NullPointerException if list or keyField is set to null.
     * @throws IllegalArgumentException if the list is not composed of Maps
     */

    static public Object getStructuredListObject(List list, String keyField, Object key) {
        if (list == null) { throw new NullPointerException("Cannot search null list"); }
        if (keyField == null) { throw new NullPointerException("Cannot search for null keyField"); }
        Object row;
        Object foundKey;
        for (Iterator i = list.iterator(); i.hasNext();) {
            // could handle generic objects via Codec.getValue(row, keyField); instead
            row = i.next();
            foundKey = Struct.getValue(row, keyField);  
            if (foundKey == null && key==null) {
                return row;
            } else {
                if (foundKey!=null && foundKey.equals(key)) {
                    return row;
                }
            }
        }
        return null;
    }

    
    /* It would be nice if this was implemented :) 
    public List filterStructuredList(List list, TopLevelExpression expression) {
        return null;
    }
    */

    /** Searches a structured list for a particular column. The list is presumed to be a List of Maps,
     *  each of which contains a particular key. The value of this key is retrieved from each
     *  Map, and added to a new List, which is then returned to the user. If the
     *  value of that key is null for a particular Map, then the null value is added to the
     *  returned list.
     *
     *  <p>For example, in the list:
     *  <pre>
     *  list = [
     *    0: { systemId = "abc", systemTimezone = "dalby" }
     *    1: { systemId = "def", systemTimezone = "london" }
     *    2: { systemId = "ghi", systemTimezone = "new york" }
     *    3: null
     *    4: { systemId = "jkl", systemTimezone = "melbourne" }
     *  ]
     *  </pre>
     *
     *  <p><code>getStructuredListColumn(list, "systemId")</code> would return a new List with
     *  three elements, i.e.
     *
     *  <pre>
     *  list = [
     *    0: "abc"
     *    1: "def"
     *    2: "ghi"
     *    3: null
     *    4: "jkl"
     *  ]
     *  </pre>
     *
     * @param list The list to search.
     * @param columnName The key of the entry in each map to retrieve
     *
     * @return a List of Objects
     *
     * @throws NullPointerException if list or columnName is set to null.
     */
    public static List getStructuredListColumn(List list, String columnName) {
        if (list == null) {
            throw new NullPointerException("list must not be empty");
        }

        if (columnName == null) {
            throw new NullPointerException("columnName must not be empty");
        }

        if (list.size() == 0) {
            return Collections.EMPTY_LIST;
        }

        ArrayList result = new ArrayList(list.size());
        Iterator it = list.iterator();

        while (it.hasNext()) {
                Object obj = it.next();
                if (obj instanceof Map) {
                Map map = (Map) obj;
                    if (map==null) {
                        result.add(null);
                    } else {
                            Object o = map.get(columnName);
                            result.add(o);
                    }
                } else {
                        Object o = getValue(obj, columnName);
                        result.add(o);
                }
        }

        return result;
    }


    /** This method returns a human-readable version of a structured list.
     * The output of this list looks similar to the following:
     *
     * <pre style="code">
     *   topLevelName = [
     *     0: 'stringValue'
     *     1: null
     *     2: (WeirdObjectClass) "toString() output of weirdObject"
     *     3 = {
     *         mapElement =&gt; ...,
     *         ...
     *       }
     *     4 = [
     *         0: listElement
     *         ...
     *       ]
     *     5 = (
     *         setElement
     *     )
     *     ...
     *   ]
     * </pre>
     *
     * Strings are represented as their own values in quotes; null values
     * are represented with the text <code>null</code>, and structured maps
     * and structured lists contained within this list are recursed into.
     *
     * @param topLevelName The name to assign to the list in the first row of output
     * @param list         The list we wish to represent as a string
     * @return             A human-readable version of a structured list
     */
    static public String structuredListToString(String topLevelName, List list) {
        String s;
        Object value;
        int index = 0;

                if (list==null) {
                        return topLevelName + " = (List) null\n";
                }

        s = topLevelName + " = [\n";

        for (Iterator i = list.iterator(); i.hasNext();) {
            value = i.next();

            if (value == null) {
                s = s + "  " + index + ": null\n";
            } else if (value instanceof String) {
                s = s + "  " + index + ": '" + Text.getDisplayString("", (String) value) + "'\n";
                        } else if (value.getClass().isArray()) {
                                List wrapper = Arrays.asList((Object[]) value);
                                s = s + "  " + index + ": (" + value.getClass() + ") " + Text.indent("  ", structuredListToString(String.valueOf(index), wrapper));
            } else if (value instanceof Map) {
                s = s + Text.indent("  ", structuredMapToString(String.valueOf(index), (Map) value));
            } else if (value instanceof List) {
                s = s + Text.indent("  ", structuredListToString(String.valueOf(index), (List) value));
                        } else if (value instanceof Set) {
                                s = s + Text.indent("  ", structuredSetToString(String.valueOf(index), (Set) value));
            } else {
                s = s + "  " + index + ": (" + Text.getLastComponent(value.getClass().getName()) + ") " + Text.getDisplayString("", value.toString()) + "\n";
            }

            index = index + 1;
        }

        s = s + "]\n";

        return s;
    }

        /** This method returns a human-readable version of a structured set.
         * The output of this set looks similar to the following:
         *
         * <pre style="code">
         *   topLevelName = (
         *     0: 'stringValue'
         *     1: null
         *     2: (WeirdObjectClass) "toString() output of weirdObject"
         *     3 = {
         *         mapElement =&gt; ...,
         *         ...
         *       }
         *     4 = [
         *         0: listElement
         *         ...
         *       ]
         *     5 = (
         *         setElement
         *       )
         *     ...
         *   )
         * </pre>
         *
         * Strings are represented as their own values in quotes; null values
         * are represented with the text <code>null</code>, and structured maps
         * and structured lists contained within this list are recursed into.
         *
         * @param topLevelName The name to assign to the list in the first row of output
         * @param set          The set we wish to represent as a string
         * @return             A human-readable version of a structured list
         */
        static public String structuredSetToString(String topLevelName, Set set) {
                String s;
                Object value;
                int index = 0;

                if (set==null) {
                        return topLevelName + " = (Set) null\n";
                }

                s = topLevelName + " = (\n";

                for (Iterator i = set.iterator(); i.hasNext();) {
                        value = i.next();

                        if (value == null) {
                                s = s + "  " + index + ": null\n";
                        } else if (value instanceof String) {
                                s = s + Text.getDisplayString("", (String) value) + "'\n";
                        } else if (value.getClass().isArray()) {
                                List wrapper = Arrays.asList((Object[]) value);
                                s = s + Text.indent("  ", structuredListToString(String.valueOf(index), wrapper));
                        } else if (value instanceof Map) {
                                s = s + Text.indent("  ", structuredMapToString(String.valueOf(index), (Map) value));
                        } else if (value instanceof List) {
                                s = s + Text.indent("  ", structuredListToString(String.valueOf(index), (List) value));
                        } else if (value instanceof Set) {
                                s = s + Text.indent("  ", structuredSetToString(String.valueOf(index), (Set) value));
                        } else {
                                s = s + "  (" + Text.getLastComponent(value.getClass().getName()) + ") " + Text.getDisplayString("", value.toString()) + "\n";
                        }

                        index = index + 1;
                }

                s = s + ")\n";

                return s;
        }

    /** This method returns a human-readable version of a structured map.
     * The output of this list looks similar to the following:
     *
     * <pre style="code">
     *   topLevelName = {
     *     apples =&gt; 'stringValue'
     *     rhinocerouseses =&gt; null
     *     weirdObjectValue =&gt; (WeirdObjectClass) "toString() output of weirdObject"
     *     mapValue = {
     *         mapElement =&gt; ...
     *         ...
     *       }
     *     listValue = [
     *         0: listElement
     *         ...
     *       ]
     *     setValue = (
     *         setElement
     *       )
     *     ...
     *   ]
     * </pre>
     *
     * Keys within the map are sorted alphabetically before being enumerated.
     *
     * Strings are represented as their own values in quotes; null values
     * are represented with the text <code>null</code>, and structured maps
     * and structured lists contained within this list are recursed into.
     *
     * @param topLevelName The name to assign to the list in the first row of output
     * @param map          The map we wish to represent as a string
     * @return             A human-readable version of a structured map
     */
    static public String structuredMapToString(String topLevelName, Map map) {
        String s;
        String key;
        Object value;

                if (map==null) {
                        return topLevelName + " = (Map) null\n";
                }

                // sort map output by key name
        List list = new ArrayList(map.keySet());
        Collections.sort(list, new ListContainingNullComparator());

        s = topLevelName + " = {\n";

        for (Iterator i = list.iterator(); i.hasNext();) {
            key = (String) i.next();
            value = map.get(key);

            if (value == null) {
                s = s + "  " + ((key == null) ? "null" : key) + " => null\n";
            } else if (value instanceof String) {
                s = s + "  " + ((key == null) ? "null" : key) + " => '" + Text.getDisplayString(key, (String) value) + "'\n";
                        } else if (value.getClass().isArray()) {
                                //List wrapper = Arrays.asList((Object[]) value);
                                //s = s + Text.indent("  ", structuredListToString(key, wrapper));
                                if (value instanceof Object[]) {
                        List wrapper = Arrays.asList((Object[])value);
                        s = s + Text.indent("  ", structuredListToString(key, wrapper));
                } else if (value instanceof double[]) {
                        // @TODO other primitive array types
                        // @TODO convert directly probably
                        // @XXX this displays primitive double types as (Double), not (double)
                        double[] daSrc = (double[]) value;
                        Double[] daTgt = new Double[daSrc.length];
                        for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                        List arrayList = Arrays.asList((Object[])daTgt);
                        s = s + Text.indent("  ", structuredListToString(key, arrayList));
                } else if (value instanceof int[]) {
                        int[] daSrc = (int[]) value;
                        Integer[] daTgt = new Integer[daSrc.length];
                        for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                        List arrayList = Arrays.asList((Object[])daTgt);
                        s = s + Text.indent("  ", structuredListToString(key, arrayList));

                } else {
                        throw new UnsupportedOperationException("Cannot convert primitive array to String");
                }
                                
            } else if (value instanceof Map) {
                s = s + Text.indent("  ", structuredMapToString(key, (Map) value));
            } else if (value instanceof List) {
                s = s + Text.indent("  ", structuredListToString(key, (List) value));
                        } else if (value instanceof Set) {
                                s = s + Text.indent("  ", structuredSetToString(key, (Set) value));
            } else {
                s = s + "  " + ((key == null) ? "null" : key) + " => (" + Text.getLastComponent(value.getClass().getName()) + ") " + Text.getDisplayString(key, value.toString()) + "\n";
            }
        }

        s = s + "}\n";

        return s;
    }


        /** This method returns a human-readable version of an array object that contains
         * structured lists/maps/sets. Bear in mind that the array object itself isn't 
         * considered 'structured' by the definitions at the top of this class, or
         * at least, it won't until this is added to the other structured parsers/readers.
         *
         * <pre style="code">
         *   topLevelName[] = [
         *     0: 'stringValue'
         *     1: null
         *     2: (WeirdObjectClass) "toString() output of weirdObject"
         *     3 = {
         *         mapElement =&gt; ...,
         *         ...
         *       }
         *     4 = [
         *         0: listElement
         *         ...
         *       ]
         *     5 = (
         *         setElement
         *     )
         *     ...
         *   ]
         * </pre>
         *
         * Strings are represented as their own values in quotes; null values
         * are represented with the text <code>null</code>, and structured maps
         * and structured lists contained within this list are recursed into.
         *
         * @param topLevelName The name to assign to the list in the first row of output
         * @param list         The list we wish to represent as a string
         * @return             A human-readable version of a structured list
         */
        static public String arrayToString(String topLevelName, Object list) {
                if (list==null) {
                        return topLevelName + "[] = (Array) null\n";
                }
                if (!list.getClass().isArray()) {
                        throw new IllegalArgumentException("object must be array");
                }
                List wrapper = Arrays.asList((Object[]) list);
                return structuredListToString(topLevelName + "[]", wrapper); 
        }

        
    /**
     * Converts a java List into javascript
     *
     * @param list the list to convert into javascript
     *
     * @return the javascript version of this list.
     */
    static public String structuredListToJson(List list)
    {
        return structuredListToJson(list, "microsoft");
    }
    
        /**
     * Converts a java List into javascript
     *
     * @param list the list to convert into javascript
     *
     * @return the javascript version of this list.
     */
    public static String structuredListToJson(List list, String jsonFormat)
    {
        StringBuilderWriter w = new StringBuilderWriter(list.size() * 2);
        try {
                structuredListToJson(w, list, jsonFormat);
                } catch (IOException e) {
                        throw new IllegalStateException("IOException in StringBuilderWriter", e);
                }
        return w.toString();
    }
    
    public static void structuredListToJson(Writer w, List list, String jsonFormat) throws IOException {
        if (list==null) {
                w.append("null");
                return;
        }
        
        Object value;
        int index = 0;
        w.append('[');
        for (Iterator i = list.iterator(); i.hasNext(); ) {
            value = i.next();
            if (value == null) {
                w.append("null");
            } else if (value instanceof String) {
                w.append('\"').append(Text.escapeJavascript((String) value)).append('\"'); 
            } else if (value instanceof WriteJsonFormat) {
                ((WriteJsonFormat) value).writeJsonFormat(w,  jsonFormat);
            } else if (value instanceof ToJsonFormat) {
                w.append(((ToJsonFormat) value).toJson(jsonFormat));
            } else if (value instanceof ToJson) {
                w.append(((ToJson) value).toJson());
            } else if (value instanceof ToStringReturnsJson) {
                w.append(value.toString());
            } else if (value instanceof Map) {
                structuredMapToJson(w, (Map) value, jsonFormat); // @TODO pass in stringbuffer to pvt method
            } else if (value instanceof List) {
                structuredListToJson(w, (List) value, jsonFormat);
            } else if (value instanceof Number) {
                w.append(value.toString());
            } else if (value instanceof Boolean) {
                w.append(value.toString());
            } else if (value instanceof java.util.Date) {
                // MS-compatible JSON encoding of Dates:
                // see http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx
                w.append(toDate((java.util.Date)value, jsonFormat));
            } else if (value.getClass().isArray()) {
                        if (value instanceof Object[]) {
                                List arrayList = Arrays.asList((Object[])value);
                                structuredListToJson(w, (List)arrayList, jsonFormat);
                        } else if (value instanceof double[]) {
                        // @TODO other primitive array types
                                // @TODO convert directly probably
                                double[] daSrc = (double[]) value;
                                Double[] daTgt = new Double[daSrc.length];
                                for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                                List arrayList = Arrays.asList((Object[])daTgt);
                                structuredListToJson(w, (List) arrayList, jsonFormat);
                        } else if (value instanceof int[]) {
                                int[] daSrc = (int[]) value;
                                Integer[] daTgt = new Integer[daSrc.length];
                                for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                                List arrayList = Arrays.asList((Object[])daTgt);
                                structuredListToJson(w, (List) arrayList, jsonFormat);
                        } else {
                                throw new UnsupportedOperationException("Cannot convert primitive array to JSON");
                        }
            } else {
                throw new RuntimeException("Cannot translate Java object " +
                    value.getClass().getName() + " to javascript value");
            }
            index = index + 1;
            if (i.hasNext()) {
                w.append(',');
            }
        }
        w.append("]\n");
        // return s.toString();
    }

     /** Converts a java map into javascript  
     *
     * @param map the Map to convert into javascript
     *
     * @return a javascript version of this Map
     */
    static public String structuredMapToJson(Map map)
    {
                return structuredMapToJson(map, DATE_FORMAT_MICROSOFT);
    }

    
    /** Converts a java map into javascript  
     *
     * @param map the Map to convert into javascript
     *
     * @return a javascript version of this Map
     */
    public static String structuredMapToJson(Map map, String jsonFormat) {
            StringBuilderWriter w = new StringBuilderWriter();
            try {
                        structuredMapToJson(w, map, jsonFormat);
                } catch (IOException e) {
                        throw new IllegalStateException("IOException in StringBuilderWriter", e);
                }
            return w.toString();
    }
   
    public static void structuredMapToJson(Writer w, Map map, String jsonFormat) throws IOException {
        if (map==null) {
                w.append("null");
                return;
        }
        
       Map.Entry entry;
       // String s;
       Object key;
       String keyJson;
       Object value;
       List list = new ArrayList(map.keySet());

       Collections.sort(list, new ListComparator());
       boolean isFirst = true;

       w.append("{");

       for (Iterator i = list.iterator(); i.hasNext();) {
           key = (Object) i.next();
           if (key instanceof String) {
                   keyJson = "\"" + Text.escapeJavascript((String) key) + "\"";
           } else if (key instanceof Number) {
                   keyJson = "\"" + String.valueOf(key) + "\""; // coerce numeric keys to strings
           } else {
                   throw new IllegalArgumentException("Cannot convert key type " + key.getClass().getName() + " to javascript value");
           }
           value = map.get(key);
           if (key == null || key.equals("")) {
               continue; // don't allow null or empty keys, 
           } else if (value == null) {
               continue; // don't bother transferring null values to javascript
           } else if (value instanceof String) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append( ": \"");
                   w.append(Text.escapeJavascript((String) value));
                   w.append("\"");
           } else if (value instanceof WriteJsonFormat) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   ((WriteJsonFormat) value).writeJsonFormat(w,  jsonFormat);
           } else if (value instanceof ToJsonFormat) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(((ToJsonFormat) value).toJson(jsonFormat));
           } else if (value instanceof ToJson) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(((ToJson) value).toJson());
           } else if (value instanceof ToStringReturnsJson) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(value.toString());
           } else if (value instanceof Map) {
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               structuredMapToJson(w, (Map) value, jsonFormat);
           } else if (value instanceof List) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   structuredListToJson(w, (List) value, jsonFormat);
           } else if (value instanceof Number) {
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               w.append(value.toString());
           } else if (value instanceof Boolean) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(value.toString());
           } else if (value instanceof java.util.Date) {
                // MS-compatible JSON encoding of Dates:
                // see http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               w.append(toDate((java.util.Date)value, jsonFormat));
           } else if (value.getClass().isArray()) {
                   
                  if (value instanceof Object[]) {
                      List arrayList = Arrays.asList((Object[])value);
                      if (!isFirst) { w.append(","); }
                      w.append(keyJson);
                      w.append(": ");
                      structuredListToJson(w, (List)arrayList, jsonFormat);
                  } else if (value instanceof double[]) {
                  // @TODO other primitive array types
                  // @TODO convert directly probably
                          double[] daSrc = (double[]) value;
                          Double[] daTgt = new Double[daSrc.length];
                          for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                          List arrayList = Arrays.asList((Object[])daTgt);
                          if (!isFirst) { w.append(","); }
                          w.append(keyJson);
                          w.append(": ");
                          structuredListToJson(w, (List)arrayList, jsonFormat);
                  } else if (value instanceof int[]) {
                  // @TODO other primitive array types
                  // @TODO convert directly probably
                          int[] daSrc = (int[]) value;
                          Integer[] daTgt = new Integer[daSrc.length];
                          for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                          List arrayList = Arrays.asList((Object[])daTgt);
                          if (!isFirst) { w.append(","); }
                          w.append(keyJson);
                          w.append(": ");
                          structuredListToJson(w, (List)arrayList, jsonFormat);
                  } else {
                          throw new UnsupportedOperationException("Cannot convert primitive array to JSON");
                  }
           } else {
               throw new RuntimeException("Cannot translate Java object " + value.getClass().getName() + " to javascript value");
           }
           isFirst = false;
       }

       w.append("}\n");
       // return s;
   }
        
        
        /**
     * Converts a java List into javascript, whilst filtering the keys of any Maps to only those in validKeys
     *
     * @param list the list to convert into javascript
     * @param jsonFormat the jsonFormat
     * @param validKeys 
     *
     * @return the javascript version of this list.
     */
    public static String structuredListToFilteredJson(List list, String jsonFormat, String...validKeys) {
        StringBuilderWriter w = new StringBuilderWriter(list.size() * 2);
        try {
                structuredListToFilteredJson(w, list, jsonFormat, validKeys);
                } catch (IOException e) {
                        throw new IllegalStateException("IOException in StringBuilderWriter", e);
                }
        return w.toString();
    }

        /**
     * Converts a java Map into javascript, whilst filtering the keys of any Maps to only those in validKeys
     *
     * @param map the map to convert into javascript
     * @param jsonFormat the jsonFormat
     * @param validKeys 
     *
     * @return the javascript version of this list.
     */
    public static String structuredMapToFilteredJson(Map map, String jsonFormat, String...validKeys) {
        StringBuilderWriter w = new StringBuilderWriter();
        try {
                structuredMapToFilteredJson(w, map, jsonFormat, validKeys);
                } catch (IOException e) {
                        throw new IllegalStateException("IOException in StringBuilderWriter", e);
                }
        return w.toString();
    }

    
    public static void structuredListToFilteredJson(Writer w, List list, String jsonFormat, String... validKeys) throws IOException {
        Object value;
        int index = 0;
        w.append('[');
        for (Iterator i = list.iterator(); i.hasNext(); ) {
            value = i.next();
            if (value == null) {
                w.append("null");
            } else if (value instanceof String) {
                w.append('\"').append(Text.escapeJavascript((String) value)).append('\"'); 
            } else if (value instanceof ToJsonFormat) {
                w.append(((ToJsonFormat) value).toJson(jsonFormat));
            } else if (value instanceof ToJson) {
                w.append(((ToJson) value).toJson());
            } else if (value instanceof ToStringReturnsJson) {
                w.append(value.toString());
            } else if (value instanceof Map) {
                structuredMapToFilteredJson(w, (Map) value, jsonFormat, validKeys); // @TODO pass in stringbuffer to pvt method
            } else if (value instanceof List) {
                structuredListToFilteredJson(w, (List) value, jsonFormat, validKeys);
            } else if (value instanceof Number) {
                w.append(value.toString());
            } else if (value instanceof Boolean) {
                w.append(value.toString());
            } else if (value instanceof java.util.Date) {
                // MS-compatible JSON encoding of Dates:
                // see http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx
                w.append(Struct.toDate((java.util.Date)value, jsonFormat));
            } else if (value.getClass().isArray()) {
                        if (value instanceof Object[]) {
                                List arrayList = Arrays.asList((Object[])value);
                                structuredListToFilteredJson(w, (List)arrayList, jsonFormat, validKeys);
                        } else if (value instanceof double[]) {
                        // @TODO other primitive array types
                                // @TODO convert directly probably
                                double[] daSrc = (double[]) value;
                                Double[] daTgt = new Double[daSrc.length];
                                for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                                List arrayList = Arrays.asList((Object[])daTgt);
                                structuredListToFilteredJson(w, (List) arrayList, jsonFormat, validKeys);
                        } else if (value instanceof int[]) {
                                int[] daSrc = (int[]) value;
                                Integer[] daTgt = new Integer[daSrc.length];
                                for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                                List arrayList = Arrays.asList((Object[])daTgt);
                                structuredListToFilteredJson(w, (List) arrayList, jsonFormat, validKeys);
                        } else {
                                throw new UnsupportedOperationException("Cannot convert primitive array to JSON");
                        }
            } else {
                throw new RuntimeException("Cannot translate Java object " +
                    value.getClass().getName() + " to javascript value");
            }
            index = index + 1;
            if (i.hasNext()) {
                w.append(',');
            }
        }
        w.append("]");  // removed \n
    }

   public static void structuredMapToFilteredJson(Writer w, Map map, String jsonFormat, String... validKeys) throws IOException {
       // String s;
       String keyJson = null;
       Object value;
       
       /* List list = new ArrayList(map.keySet());
       Collections.sort(list, new ListComparator());
       */
       
       boolean isFirst = true;

       w.append("{");

       for (String key : validKeys) {
           // key = (Object) i.next();
           value = map.get(key);
           if (value != null) {
                   if (key instanceof String) {
                           keyJson = "\"" + key + "\"";
                   } else {
                           throw new IllegalArgumentException("Cannot convert key type " + key.getClass().getName() + " to javascript value");
                   }
           }
           if (key == null || key.equals("")) {
               continue; // don't allow null or empty keys, 
           } else if (value == null) {
               continue; // don't bother transferring null values to javascript
           } else if (value instanceof String) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append( ": \"");
                   w.append(Text.escapeJavascript((String) value));
                   w.append("\"");
           } else if (value instanceof ToJsonFormat) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(((ToJsonFormat) value).toJson(jsonFormat));
           } else if (value instanceof ToJson) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(((ToJson) value).toJson());
           } else if (value instanceof ToStringReturnsJson) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(value.toString());
           } else if (value instanceof Map) {
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               structuredMapToFilteredJson(w, (Map) value, jsonFormat, validKeys);
           } else if (value instanceof List) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   structuredListToFilteredJson(w, (List) value, jsonFormat, validKeys);
           } else if (value instanceof Number) {
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               w.append(value.toString());
           } else if (value instanceof Boolean) {
                   if (!isFirst) { w.append(","); }
                   w.append(keyJson);
                   w.append(": ");
                   w.append(value.toString());
           } else if (value instanceof java.util.Date) {
                // MS-compatible JSON encoding of Dates:
                // see http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx
                   if (!isFirst) { w.append(","); }
               w.append(keyJson);
               w.append(": ");
               w.append(Struct.toDate((java.util.Date)value, jsonFormat));
           } else if (value.getClass().isArray()) {
                   
                  if (value instanceof Object[]) {
                      List arrayList = Arrays.asList((Object[])value);
                      if (!isFirst) { w.append(","); }
                      w.append(keyJson);
                      w.append(": ");
                      structuredListToFilteredJson(w, (List)arrayList, jsonFormat, validKeys);
                  } else if (value instanceof double[]) {
                  // @TODO other primitive array types
                  // @TODO convert directly probably
                          double[] daSrc = (double[]) value;
                          Double[] daTgt = new Double[daSrc.length];
                          for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                          List arrayList = Arrays.asList((Object[])daTgt);
                          if (!isFirst) { w.append(","); }
                          w.append(keyJson);
                          w.append(": ");
                          structuredListToFilteredJson(w, (List)arrayList, jsonFormat, validKeys);
                  } else if (value instanceof int[]) {
                  // @TODO other primitive array types
                  // @TODO convert directly probably
                          int[] daSrc = (int[]) value;
                          Integer[] daTgt = new Integer[daSrc.length];
                          for (int j=0; j<daSrc.length; j++) { daTgt[j]=daSrc[j]; }
                          List arrayList = Arrays.asList((Object[])daTgt);
                          if (!isFirst) { w.append(","); }
                          w.append(keyJson);
                          w.append(": ");
                          structuredListToFilteredJson(w, (List)arrayList, jsonFormat, validKeys);
                  } else {
                          throw new UnsupportedOperationException("Cannot convert primitive array to JSON");
                  }
           } else {
               throw new RuntimeException("Cannot translate Java object " + value.getClass().getName() + " to javascript value");
           }
           isFirst = false;
       }

       w.append("}");  // removed \n
   }

   
    
    /** Convert a date object to it's JSON representation.
     * 
     * <p>As there's no real standard for this, a type format is used to define what kind of Dates your 
     * going to get on the Json side.
     * 
     * @param d a Date object
     * @param jsonFormat either "microsoft" or "numeric"
     * 
     * @return A date in json representation.
     * 
     * @see <a href="http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx">http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx</a>
     */
    static public String toDate(Date d, String jsonFormat) {
                if (jsonFormat==null || jsonFormat.equals("microsoft")) {
                        return "\"\\/Date(" + d.getTime() +  ")\\/\"";  
                } else {
                        return String.valueOf(d.getTime());
                }
    }




    
    /** Create a structured Map out of key / value pairs. Keys must be Strings.
     * 
     * <p>So the value of <code>Struct.newStructuredMap("thing", 1L, "otherThing", "value");</code> is a map
     * with two entries:
     * <ul><li>an entry with key "thing" and value new Long(1), and 
     * <li>an entry  with key "otherThing" and value "value".
     * </ul> 
     * 
     * @param keyValuePairs a list of key / value pairs 
     * 
     * @return a Map as described above
     * 
     * @throws ClassCastException if any of the supplied keys is not a String
     */
    // looking forward to when statically defined Maps become a Java language construct
    static public Map<String, Object> newStructuredMap(Object... keyValuePairs) {
        if (keyValuePairs.length%2==1) { throw new IllegalArgumentException("keyValuePairs must have even number of elements"); }
        Map<String, Object> map = new HashMap();
        for (int i=0; i<keyValuePairs.length; i+=2) {
                String key = (String) keyValuePairs[i];
                map.put(key, keyValuePairs[i + 1]);
        }
        return map;
    }

        /** Rename a structured column, as returned from a Spring JdbcTemplate query. This method will iterate
         * throw all rows of a table, replacing any srcColumnName keys with destColumnName
         * 
         * @param rows the table being modified
         * @param srcColumnName the name of the row key (column) being replaced
         * @param destColumnName the new name of the row key (column)
         */
        public static void renameStructuredListColumn(List<Map<String, Object>> rows, String srcColumnName, String destColumnName) {
                if (srcColumnName == null) { throw new NullPointerException("null srcColumnName"); }
                if (destColumnName == null) { throw new NullPointerException("null destColumnName"); }
                if (srcColumnName.equals(destColumnName)) { return; }
                
                for (int i=0; i<rows.size(); i++) {
                        Map<String,Object> row = rows.get(i);
                        if (row.containsKey(srcColumnName)) {
                                row.put(destColumnName, row.get(srcColumnName));
                                row.remove(srcColumnName);
                        }
                }
        }

        /** Add a structured column containing a constant value. This method will iterate through all 
         * rows of a table, adding a new newColumnName key with the supplied value.
         * 
         * @param rows the table being modified
         * @param newColumnName the name of the row key (column) being added
         * @param value the value to add to the row
         */
        public static void addStructuredListColumn(List<Map<String, Object>> rows, String newColumnName, Object value) {
                for (int i=0; i<rows.size(); i++) {
                        Map<String,Object> row = rows.get(i);
                        row.put(newColumnName, value);
                }
        }

    static {
        // NB: these used to be ConcurrentReaderHashMaps, but I didn't want to
        // bring concurrent.jar into the classpath.
        gettersCache = new ConcurrentHashMap();
        settersCache = new ConcurrentHashMap();
    }
}