/**
    * Redistribution and use of this software and associated documentation ("Software"), with or
    * without modification, are permitted provided that the following conditions are met:
    *
    * 1. Redistributions of source code must retain copyright statements and notices. Redistributions
    * must also contain a copy of this document.
    *
    * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
    * conditions and the following disclaimer in the documentation and/or other materials provided with
   * the distribution.
   *
   * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software
   * without prior written permission of Intalio, Inc. For written permission, please contact
   * info@exolab.org.
   *
   * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in
   * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of
   * Intalio, Inc.
   *
   * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
   *
   * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR
   * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
   * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS
   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
   * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   *
   * Copyright 1999-2003 (C) Intalio, Inc. All Rights Reserved.
   *
   * $Id$
   */
  
  package org.exolab.castor.mapping.loader;
  
  import java.lang.reflect.Array;
  import java.lang.reflect.Field;
  import java.lang.reflect.Method;
  import java.lang.reflect.Modifier;
  import java.lang.reflect.InvocationTargetException;
  import java.util.Enumeration;
  import java.util.Iterator;
  
  import org.castor.core.util.Messages;
  import org.exolab.castor.core.exceptions.CastorIllegalStateException;
  import org.exolab.castor.mapping.AbstractFieldHandler;
  import org.exolab.castor.mapping.ExtendedFieldHandler;
  import org.exolab.castor.mapping.FieldDescriptor;
  import org.exolab.castor.mapping.FieldHandler;
  import org.exolab.castor.mapping.GeneralizedFieldHandler;
  import org.exolab.castor.mapping.TypeConvertor;
  import org.exolab.castor.mapping.CollectionHandler;
  import org.exolab.castor.mapping.MappingException;
  import org.exolab.castor.mapping.MappingRuntimeException;
  import org.exolab.castor.util.IteratorEnumeration;
  
  /**
   * A field handler that knows how to get/set the values of a field directly or through the get/set
   * methods. Uses reflection.
   * <p>
   * Note: the field Java type is obtained from {@link TypeInfo#getFieldType()}, but if the field is a
   * collection, the actual field/accessor type is obtained from {@link TypeInfo#getCollectionHandler}
   * and the object to create (with {@link #newInstance(Object)}) is the former field type.
   * 
   * @author <a href="arkin@intalio.com">Assaf Arkin</a>
   * @version $Revision$ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $
   */
  public final class FieldHandlerImpl<T> extends AbstractFieldHandler<T> {
    /**
     * The prefix for an "add" method
     **/
    private static final String ADD_PREFIX = "add";
  
    /**
     * The prefix for an "enum" method
     */
    private static final String ENUM_PREFIX = "enum";
  
    /**
     * The prefix for an "iter" method
     */
    private static final String ITER_PREFIX = "iter";
  
    /**
     * The underlying field handler used by this handler.
     */
    private final FieldHandler<T> _handler;
  
    /**
     * The Java field described and accessed through this descriptor.
     */
    private final Field _field;
  
    /**
     * The sequence of methods used to obtain the nested field. May be null.
     */
    private Method[] _getSequence;
 
   /**
    * The sequence of methods used to create the nested object. May be null.
    */
   private Method[] _setSequence;
 
   /**
    * The method used to "incrementally" set the value of this field. This is only used if the field
    * is a collection
    */
   private Method _addMethod;
 
   /**
    * The method used to enumerate entries of a container.
    */
   private Method _enumMethod;
 
   /**
    * The method used to iterate over a container.
    */
   private Method _iterMethod;
 
   /**
    * The method used to obtain the value of this field. May be null.
    */
   private Method _getMethod;
 
   /**
    * The method used to set the value of this field. May be null.
    */
   private Method _setMethod;
 
   /**
    * The method used to check if the value of this field exists. May be null.
    */
   private Method _hasMethod;
 
   /**
    * The method used to delete the value of this field. May be null.
    */
   private Method _deleteMethod;
 
   /**
    * The method used to create a new instance of the field.
    */
   private Method _createMethod;
 
   /**
    * The Java field name.
    */
   private final String _fieldName;
 
   /**
    * The Java field type.
    */
   private final Class _fieldType;
 
   /**
    * True if this field is an immutable type.
    */
   private final boolean _immutable;
 
   /**
    * The default value for primitive fields. Will be set if the field is null.
    */
   private final Object _default;
 
   /**
    * Convertor to apply when setting the value of the field. Converts from the value to the field
    * type. Null if no convertor is required.
    */
   private TypeConvertor _convertTo = null;
 
   /**
    * Convertor to apply when reading the value of the field. Converts from the field type to the
    * return value. Null if no convertor is required.
    */
   private TypeConvertor _convertFrom = null;
 
   /**
    * The collection handler for multi valued fields.
    */
   private final CollectionHandler<T> _colHandler;
 
   /**
    * Construct a new field handler for the specified field. The field must be public, and may not be
    * static or transient. The field name is determined from the Java field, the type from the type
    * information.
    * 
    * @param handler
    * @param typeInfo Type information
    */
   public FieldHandlerImpl(FieldHandler<T> handler, TypeInfo typeInfo) {
     _handler = handler;
     _field = null;
     _fieldName = handler.toString();
     _fieldType = Types.typeFromPrimitive(typeInfo.getFieldType());
     _immutable = typeInfo.isImmutable();
     _default = typeInfo.getDefaultValue();
     _convertTo = typeInfo.getConvertorTo();
     _convertFrom = typeInfo.getConvertorFrom();
     _colHandler = typeInfo.getCollectionHandler();
   }
 
   /**
    * Construct a new field handler for the specified field. The field must be public, and may not be
    * static or transient. The field name is determined from the Java field, the type from the type
    * information.
    * 
    * @param field The field being described
    * @param typeInfo Type information
    * @throws MappingException If the field is not public, is static or transient
    */
   public FieldHandlerImpl(Field field, TypeInfo typeInfo) throws MappingException {
     if (field.getModifiers() != Modifier.PUBLIC
         && field.getModifiers() != (Modifier.PUBLIC | Modifier.VOLATILE))
       throw new MappingException("mapping.fieldNotAccessible", field.getName(),
           field.getDeclaringClass().getName());
     _handler = null;
     _field = field;
     _fieldType = Types.typeFromPrimitive(typeInfo.getFieldType());
     _fieldName = field.getName() + "(" + field.getType().getName() + ")";
     _immutable = typeInfo.isImmutable();
     // If the field is of a primitive type or if it is required
     // we use the default value
     if (_field.getType().isPrimitive())
       _default = typeInfo.getDefaultValue();
     else
       _default = null;
     _convertTo = typeInfo.getConvertorTo();
     _convertFrom = typeInfo.getConvertorFrom();
     _colHandler = typeInfo.getCollectionHandler();
   }
 
   /**
    * Construct a new field handler for the specified field that is accessed through the accessor
    * methods (get/set). The accessor methods must be public and not static. The field name is
    * required for descriptive purposes. The field type must match the return value of the get method
    * and the single parameter of the set method. Either get or set methods are optional.
    * 
    * @param fieldName The field being described
    * @param getMethod The method used to retrieve the field value, must accept no parameters and
    *        have a return type castable to the field type
    * @param setMethod The method used to set the field value, must accept a single parameter that is
    *        castable to the field type
    * @param typeInfo Type information
    * @throws MappingException If the get or set method are not public, are static, or do not specify
    *         the proper types
    * 
    */
   public FieldHandlerImpl(String fieldName, Method[] getSequence, Method[] setSequence,
       Method getMethod, Method setMethod, TypeInfo typeInfo) throws MappingException {
     _handler = null;
     _field = null;
     if (fieldName == null)
       throw new IllegalArgumentException("Argument 'fieldName' is null");
 
     // Originally commented out by Oleg....not sure why?
     // if ( getMethod == null && setMethod == null )
     // throw new IllegalArgumentException(
     // "Both arguments 'getMethod' and 'setMethod' are null" );
 
     _getSequence = getSequence;
     _setSequence = setSequence;
 
     if (setMethod != null) {
       // -- might be an "add" method
       if (setMethod.getName().startsWith(ADD_PREFIX)) {
         Class<?> pType = setMethod.getParameterTypes()[0];
         if (pType != typeInfo.getFieldType())
           setAddMethod(setMethod);
         else
           setWriteMethod(setMethod);
       }
 
       // for(Iterator iter = setMethods.iterator(); iter.hasNext(); ) {
       // Method method = (Method) iter.next();
       //
       // if (method.getName().startsWith(ADD_PREFIX)) {
       // Class paraType = method.getParameterTypes()[0];
       //
       // if (paraType != typeInfo.getFieldType()) {
       // addMethods.add(method);
       // iter.remove();
       // }
       // }
       // }
       else
         setWriteMethod(setMethod);
     }
 
     if (getMethod != null) {
       // getMethod might be an enumeration or iteration.
       if (getMethod.getName().startsWith(ENUM_PREFIX)) {
         Class<?> rType = getMethod.getReturnType();
 
         // Check if getMethod really returns an enumeration.
         if (Enumeration.class.isAssignableFrom(rType))
           setEnumMethod(getMethod);
         else
           // If getMethod does not return an enumeration, treat it as a
           // normal getMethod.
           setReadMethod(getMethod);
       } else if (getMethod.getName().startsWith(ITER_PREFIX)) {
         Class<?> rType = getMethod.getReturnType();
 
         // Check if getMethod really returns an iterator.
         if (Iterator.class.isAssignableFrom(rType))
           setIterMethod(getMethod);
         else
           // If getMethod does not return an iterator, treat it as a normal
           // getMethod.
           setReadMethod(getMethod);
       } else
         setReadMethod(getMethod);
     }
 
     _fieldType = Types.typeFromPrimitive(typeInfo.getFieldType());
     _fieldName = fieldName + "(" + _fieldType.getName() + ")";
     _immutable = typeInfo.isImmutable();
 
     // If the field is of a primitive type or if it is required
     // we use the default value
     if (setMethod != null && setMethod.getParameterTypes()[0].isPrimitive())
       _default = typeInfo.getDefaultValue();
     else
       _default = null;
     _convertTo = typeInfo.getConvertorTo();
     _convertFrom = typeInfo.getConvertorFrom();
     _colHandler = typeInfo.getCollectionHandler();
   }
 
   public TypeConvertor getConvertFrom() {
     return _convertFrom;
   }
 
   public TypeConvertor getConvertTo() {
     return _convertTo;
   }
 
   /**
    * {@inheritDoc}
    * 
    * @see org.exolab.castor.mapping.AbstractFieldHandler#getValue(java.lang.Object)
    */
   @SuppressWarnings("unchecked")
   public T getValue(Object object) {
     T value;
 
     try {
       // If field is accessed directly, get its value. If not, we need to
       // call
       // its get method. It's possible to not have a way to access the field.
 
       if (_handler != null) {
         value = _handler.getValue(object);
       } else if (_field != null) {
         value = (T) _field.get(object);
       } else if (_enumMethod != null) {
         // If there is an enumeration method supplied, return the
         // enumeration.
         value = (T) _enumMethod.invoke(object, (Object[]) null);
       } else if (_iterMethod != null) {
         // If there is an iterator method supplied, wrap it in an
         // enumeration.
         value =
             (T) new IteratorEnumeration((Iterator<T>) _iterMethod.invoke(object, (Object[]) null));
       } else if (_getMethod != null) {
         if (_getSequence != null) {
           for (int i = 0; i < _getSequence.length; i++) {
             object = _getSequence[i].invoke(object, (Object[]) null);
             if (object == null) {
               break;
             }
           }
         }
 
         // Some of the objects in the sequence might be null, then the value
         // is null.
         // If field has 'has' method, false means field is null and do not
         // attempt to
         // call getValue. Otherwise, ????
         if (object == null || (_hasMethod != null
             && !((Boolean) _hasMethod.invoke(object, (Object[]) null)).booleanValue())) {
           value = null;
         } else {
           value = (T) _getMethod.invoke(object, (Object[]) null);
         }
       } else {
         value = null;
       }
     } catch (IllegalAccessException except) {
       throw new CastorIllegalStateException(
           Messages.format("mapping.schemaChangeNoAccess", toString()), except);
     } catch (InvocationTargetException except) {
       throw new CastorIllegalStateException(
           Messages.format("mapping.schemaChangeInvocation", toString(), except), except);
     }
 
     // -- If a collection, return an enumeration of it's values.
     // -- Only use collection handler, if there is no convertor or enum
     // method.
     if (_colHandler != null && _enumMethod == null && _iterMethod == null && _convertFrom == null) {
       if (value == null) {
         return (T) new CollectionHandlers.EmptyEnumerator<T>();
       }
       return (T) _colHandler.elements(value);
     }
 
     // If there is a convertor, apply it
     if (_convertFrom == null || value == null) {
       return value;
     }
 
     try {
       return (T) _convertFrom.convert(value);
     } catch (ClassCastException except) {
       String errorMessage = Messages.format("mapping.wrongConvertor", value.getClass().getName());
       throw new IllegalArgumentException(errorMessage, except);
     }
   }
 
   /**
    * {@inheritDoc}
    * 
    * @see org.exolab.castor.mapping.AbstractFieldHandler#setValue(java.lang.Object,
    *      java.lang.Object)
    */
   @SuppressWarnings("unchecked")
   public void setValue(Object object, T value) {
     if (_colHandler == null || _addMethod != null) {
 
       // If there is a convertor, apply conversion here.
       if (value != null && _convertTo != null) {
         try {
           value = (T) _convertTo.convert(value);
         } catch (ClassCastException except) {
           String errorMessage =
               Messages.format("mapping.wrongConvertor", value.getClass().getName());
           throw new IllegalArgumentException(errorMessage, except);
         }
       } else {
         // -- unwrap MapItem if necessary
         // if (_colHandler != null) {
         // if ((value instanceof MapItem) && (_fieldType != MapItem.class))
         // {
         // value = ((MapItem)value).getValue();
         // }
         // }
       }
 
       try {
         if (_handler != null) {
           _handler.setValue(object, value);
         } else if (_field != null) {
           _field.set(object, value == null ? _default : value);
         } else {
 
           // -- either add or set
           Method setter = selectWriteMethod(value);
 
           if (setter != null) {
             if (_getSequence != null) {
               for (int i = 0; i < _getSequence.length; i++) {
                 Object last;
 
                 last = object;
                 object = _getSequence[i].invoke(object, (Object[]) null);
                 if (object == null) {
                   // if the value is not null, we must instantiate
                   // the object in the sequence
                   if (value == null || _setSequence[i] == null) {
                     break;
                   }
                   object = Types.newInstance(_getSequence[i].getReturnType());
                   _setSequence[i].invoke(last, new Object[] {object});
                 }
               }
             }
             if (object != null) {
               if (value == null && _deleteMethod != null) {
                 _deleteMethod.invoke(object, (Object[]) null);
               } else {
                 setter.invoke(object, new Object[] {value == null ? _default : value});
               }
             }
           }
         }
         // If the field has no set method, ignore it.
         // If this is a problem, identity it someplace else.
       } catch (IllegalArgumentException except) {
         // Graceful way of dealing with unwrapping exception
         if (value == null) {
           String errorMessage = Messages.format("mapping.typeConversionNull", toString());
           throw new IllegalArgumentException(errorMessage);
         }
         String errorMessage =
             Messages.format("mapping.typeConversion", toString(), value.getClass().getName());
         throw new IllegalArgumentException(errorMessage, except);
       } catch (IllegalAccessException except) {
         // This should never happen
         String errorMessage = Messages.format("mapping.schemaChangeNoAccess", toString());
         throw new CastorIllegalStateException(errorMessage, except);
       } catch (InvocationTargetException except) {
         // This should never happen
         throw new MappingRuntimeException(except.getTargetException());
       }
     } else if (value != null) {
       Object collect;
       try {
         // Get the field value (the collection), add the value to it,
         // possibly yielding a new collection (in the case of an array),
         // and set that collection back into the field.
         if (_handler != null) {
           collect = _handler.getValue(object);
           collect = _colHandler.add(collect, value);
           if (collect != null)
             _handler.setValue(object, (T) collect);
         } else if (_field != null) {
           collect = _field.get(object);
           if (collect == null) {
             // The type of the collection.
             Class type = _field.getType();
             // -- Handle Arrays, we need to declare the array with
             // -- the correct type. The other cases are handled in
             // -- the J1CollectionHandler during the
             // -- add(collect,value) call
             if (type.isArray()) {
               Class componentType = type.getComponentType();
               Class valueType = value.getClass();
               if (componentType.isPrimitive()
                   || ((!valueType.isArray()) && (valueType != componentType))) {
                 try {
                   collect = Array.newInstance(componentType, 0);
                 } catch (Exception e) {
                   String err = "Unable to instantiate an array of '" + componentType + "' : " + e;
                   throw new CastorIllegalStateException(err, e);
                 }
               }
             }
           }
           collect = _colHandler.add(collect, value);
           if (collect != null)
             _field.set(object, collect);
 
         } else if (_getMethod != null) {
           if (_getSequence != null)
             for (int i = 0; i < _getSequence.length; i++)
               object = _getSequence[i].invoke(object, (Object[]) null);
           collect = _getMethod.invoke(object, (Object[]) null);
 
           // If we deal with a collection who is an array of primitive
           // and that has not been instantiated, we have to handle the
           // instantiation here rather than in J1CollectionHandler,
           // because we have acces to the Field object here.
           boolean setCollection = false;
           if (collect == null) {
             // The return type of the get method should be the type of the
             // collection.
             Class type = _getMethod.getReturnType();
 
             // -- Handle Arrays, we need to declare the array with
             // -- the correct type. The other cases are handled in
             // -- the J1CollectionHandler during the
             // -- add(collect,value) call
             if (type.isArray()) {
               Class componentType = type.getComponentType();
               Class valueType = value.getClass();
               if (componentType.isPrimitive()
                   || ((!valueType.isArray()) && (valueType != componentType))) {
                 try {
                   collect = Array.newInstance(componentType, 0);
                 } catch (Exception e) {
                   String err = "Unable to instantiate an array of '" + componentType + "' : " + e;
                   throw new CastorIllegalStateException(err, e);
                 }
               }
             }
             setCollection = true;
           } else {
             setCollection = collect.getClass().isArray();
           }
 
           Object tmp = _colHandler.add(collect, value);
 
           // -- make sure we do not overwrite collect unless
           // -- the new collection is not null
           if (tmp != null)
             collect = tmp;
 
           if (setCollection && (_setMethod != null))
             _setMethod.invoke(object, new Object[] {collect});
         }
       } catch (IllegalAccessException except) {
         // This should never happen
         throw new IllegalStateException(
             Messages.format("mapping.schemaChangeNoAccess", toString()));
       } catch (InvocationTargetException except) {
         // This should never happen
         throw new MappingRuntimeException(except.getTargetException());
       }
     }
   }
 
   public void resetValue(Object object) {
     if (_colHandler == null) {
 
       try {
         if (_handler != null)
           _handler.resetValue(object);
         else if (_field != null)
           _field.set(object, _default);
         else if (_setMethod != null) {
           if (_getSequence != null)
             for (int i = 0; i < _getSequence.length; i++) {
               object = _getSequence[i].invoke(object, (Object[]) null);
               if (object == null)
                 break;
             }
           if (object != null) {
             if (_deleteMethod != null)
               _deleteMethod.invoke(object, (Object[]) null);
             else
               _setMethod.invoke(object, new Object[] {_default});
           }
         }
         // If the field has no set method, ignore it.
         // If this is a problem, identity it someplace else.
       } catch (IllegalArgumentException except) {
         // Graceful way of dealing with unwrapping exception
         throw new IllegalArgumentException(
             Messages.format("mapping.typeConversionNull", toString()));
       } catch (IllegalAccessException except) {
         // This should never happen
         throw new IllegalStateException(
             Messages.format("mapping.schemaChangeNoAccess", toString()));
       } catch (InvocationTargetException except) {
         // This should never happen
         throw new MappingRuntimeException(except.getTargetException());
       }
 
     } else {
       Object collect;
 
       try {
         // Get the field value (the collection), add the value to it,
         // possibly yielding a new collection (in the case of an array),
         // and set that collection back into the field.
         if (_handler != null) {
           _handler.resetValue(object);
         } else if (_field != null) {
           collect = _field.get(object);
           collect = _colHandler.clear(collect);
           if (collect != null)
             _field.set(object, collect);
         } else if (_getMethod != null) {
           if (_getSequence != null)
             for (int i = 0; i < _getSequence.length; i++)
               object = _getSequence[i].invoke(object, (Object[]) null);
           collect = _getMethod.invoke(object, (Object[]) null);
           collect = _colHandler.clear(collect);
           if (collect != null && _setMethod != null)
             _setMethod.invoke(object, new Object[] {collect});
         }
       } catch (IllegalAccessException except) {
         // This should never happen
         throw new IllegalStateException(
             Messages.format("mapping.schemaChangeNoAccess", toString()));
       } catch (InvocationTargetException except) {
         // This should never happen
         throw new MappingRuntimeException(except.getTargetException());
       }
 
     }
   }
 
   /**
    * Creates a new instance of the object described by this field.
    * 
    * @param parent The object for which the field is created
    * @return A new instance of the field's value
    * @throws IllegalStateException This field is a simple type and cannot be instantiated
    */
   public T newInstance(Object parent) throws IllegalStateException {
     return newInstance(parent, null);
   }
 
   /**
    * Creates a new instance of the object described by this field.
    * 
    * @param parent The object for which the field is created
    * @param args the set of constructor arguments
    * @return A new instance of the field's value
    * @throws IllegalStateException This field is a simple type and cannot be instantiated
    */
   @SuppressWarnings("unchecked")
   public T newInstance(Object parent, Object[] args) throws IllegalStateException {
     if (_fieldType.isInterface() && _createMethod == null)
       return null;
 
     if ((_immutable) && ((args == null) || (args.length == 0)))
       throw new IllegalStateException(Messages.format("mapping.classNotConstructable", _fieldType));
 
     if (_handler != null) {
       if (_handler instanceof ExtendedFieldHandler)
         return (T) ((ExtendedFieldHandler<T>) _handler).newInstance(parent, args);
       return _handler.newInstance(parent);
     }
     // If we have a create method and parent object, call the create method.
     if (_createMethod != null && parent != null) {
       try {
         return (T) _createMethod.invoke(parent, args);
       } catch (IllegalAccessException except) {
         // This should never happen
         throw new IllegalStateException(
             Messages.format("mapping.schemaChangeNoAccess", toString()));
       } catch (InvocationTargetException except) {
         // This should never happen
         throw new MappingRuntimeException(except.getTargetException());
       }
     }
     return (T) Types.newInstance(_fieldType, args);
   } // -- newInstance
 
   /**
    * Mutator method used by {@link AbstractMappingLoader}.
    */
   void setRequired(final boolean required) {}
 
   /**
    * Sets the TypeConvertor used during calls to getValue
    * 
    * @param convertor the TypeConvertor to use during calls to getValue
    **/
   public void setConvertFrom(TypeConvertor convertor) {
     _convertFrom = convertor;
   } // -- setConvertFrom
 
   /**
    * Sets the TypeConvertor used during calls to setValue
    * 
    * @param convertor the TypeConvertor to use during calls to setValue
    **/
   public void setConvertTo(TypeConvertor convertor) {
     _convertTo = convertor;
   } // -- setConvertTo
 
   /**
    * Mutator method used by {@link AbstractMappingLoader} and
    * {@link org.exolab.castor.xml.Introspector}. Please understand how this method is used before
    * you start playing with it! :-)
    */
   public void setCreateMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 0)
       throw new MappingException("mapping.createMethodNoParam", method,
           method.getDeclaringClass().getName());
     _createMethod = method;
   }
 
   /**
    * Mutator method used by {@link AbstractMappingLoader} and
    * {@link org.exolab.castor.xml.Introspector}. Please understand how this method is used before
    * you start playing with it! :-)
    */
   public void setHasDeleteMethod(Method hasMethod, Method deleteMethod) throws MappingException {
     if (hasMethod != null) {
       if ((hasMethod.getModifiers() & Modifier.PUBLIC) == 0
           || (hasMethod.getModifiers() & Modifier.STATIC) != 0)
         throw new MappingException("mapping.accessorNotAccessible", hasMethod,
             hasMethod.getDeclaringClass().getName());
       if (hasMethod.getParameterTypes().length != 0)
         throw new MappingException("mapping.createMethodNoParam", hasMethod,
             hasMethod.getDeclaringClass().getName());
       _hasMethod = hasMethod;
     }
 
     if (deleteMethod != null) {
       if ((deleteMethod.getModifiers() & Modifier.PUBLIC) == 0
           || (deleteMethod.getModifiers() & Modifier.STATIC) != 0)
         throw new MappingException("mapping.accessorNotAccessible", deleteMethod,
             deleteMethod.getDeclaringClass().getName());
       if (deleteMethod.getParameterTypes().length != 0)
         throw new MappingException("mapping.createMethodNoParam", deleteMethod,
             deleteMethod.getDeclaringClass().getName());
       _deleteMethod = deleteMethod;
     }
   }
 
   /**
    * Mutator method used by {@link org.exolab.castor.xml.Introspector}. Please understand how this
    * method is used before you start playing with it! :-)
    */
   public void setReadMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 0)
       throw new MappingException("mapping.readMethodHasParam", method,
           method.getDeclaringClass().getName());
     _getMethod = method;
   }
 
   /**
    * Mutator method used by {@link org.exolab.castor.xml.Introspector}. Please understand how this
    * method is used before you start playing with it! :-)
    */
   public void setWriteMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 1)
       throw new MappingException("mapping.writeMethodNoParam", method,
           method.getDeclaringClass().getName());
     _setMethod = method;
   }
 
   /**
    * Mutator method used by {@link org.exolab.castor.xml.Introspector}. Please understand how this
    * method is used before you start playing with it! :-)
    */
   public void setAddMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 1)
       throw new MappingException("mapping.writeMethodNoParam", method,
           method.getDeclaringClass().getName());
     _addMethod = method;
 
     // -- make sure add method is not the same as the set method
     if (_addMethod == _setMethod)
       _setMethod = null;
 
   } // -- setAddMethod
 
   /**
    * Sets the enumeration method.
    */
   public void setEnumMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 0)
       throw new MappingException("mapping.readMethodHasParam", method,
           method.getDeclaringClass().getName());
 
     _enumMethod = method;
   }
 
   /**
    * Sets the iteration method.
    */
   public void setIterMethod(Method method) throws MappingException {
     if ((method.getModifiers() & Modifier.PUBLIC) == 0
         || (method.getModifiers() & Modifier.STATIC) != 0)
       throw new MappingException("mapping.accessorNotAccessible", method,
           method.getDeclaringClass().getName());
     if (method.getParameterTypes().length != 0)
       throw new MappingException("mapping.readMethodHasParam", method,
           method.getDeclaringClass().getName());
 
     _iterMethod = method;
   }
 
   /**
    * Selects the appropriate "write" method based on the value. This is used when there is an "add"
    * method and a "set" method.
    * 
    * @return the selected write method
    **/
   private Method selectWriteMethod(Object value) {
     if (_setMethod != null) {
 
       if (_addMethod == null)
         return _setMethod;
 
       if (value == null) {
         if (_default != null)
           value = _default;
         else
           return _setMethod;
       }
 
       // -- check value's class type
       Class paramType = _setMethod.getParameterTypes()[0];
 
       if (paramType.isAssignableFrom(value.getClass()))
         return _setMethod;
     }
 
     return _addMethod;
 
   } // -- selectWriteMethod
 
   /**
    * Return true if the field is a collection.
    */
   public boolean isCollection() {
     return (_colHandler != null);
   }
 
   public String toString() {
     return _fieldName;
   }
 
   /**
    * Sets the FieldDescriptor that this FieldHander is responsibile for. By setting the
    * FieldDescriptor, it allows the implementation of the FieldHandler methods to obtain information
    * about the field itself. This allows a particular implementation to become more generic and
    * reusable.
    * 
    * @param fieldDesc the FieldDescriptor to set
    */
   public void setFieldDescriptor(FieldDescriptor fieldDesc) {
     super.setFieldDescriptor(fieldDesc);
     if (_handler != null) {
       if (_handler instanceof GeneralizedFieldHandler) {
         ((GeneralizedFieldHandler) _handler).setFieldDescriptor(fieldDesc);
       }
     }
   }
 
 }