CustomMapEditor (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.beans.propertyeditors

## Class CustomMapEditor

- java.lang.Object
- - java.beans.PropertyEditorSupport
  - - org.springframework.beans.propertyeditors.CustomMapEditor

- All Implemented Interfaces:
    PropertyEditor

      public class CustomMapEditor
      extends PropertyEditorSupport

  Property editor for Maps, converting any source Map to a given target Map type.
  Since:
    2.0.1
  Author:
    Juergen Hoeller
  See Also:
    `Map`, `SortedMap`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CustomMapEditor(Class mapType)` Create a new CustomMapEditor for the given target type, keeping an incoming `null` as-is.
    `CustomMapEditor(Class mapType, boolean nullAsEmptyMap)` Create a new CustomMapEditor for the given target type.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `alwaysCreateNewMap()` Return whether to always create a new Map, even if the type of the passed-in Map already matches.
    `protected Object` | `convertKey(Object key)` Hook to convert each encountered Map key.
    `protected Object` | `convertValue(Object value)` Hook to convert each encountered Map value.
    `protected Map` | `createMap(Class mapType, int initialCapacity)` Create a Map of the given type, with the given initial capacity (if supported by the Map type).
    `String` | `getAsText()` This implementation returns `null` to indicate that there is no appropriate text representation.
    `void` | `setAsText(String text)` Convert the given text value to a Map with a single element.
    `void` | `setValue(Object value)` Convert the given value to a Map of the target type.

    - ### Methods inherited from class java.beans.PropertyEditorSupport

      `addPropertyChangeListener, firePropertyChange, getCustomEditor, getJavaInitializationString, getSource, getTags, getValue, isPaintable, paintValue, removePropertyChangeListener, setSource, supportsCustomEditor`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CustomMapEditor

          public CustomMapEditor(Class mapType)

      Create a new CustomMapEditor for the given target type, keeping an incoming `null` as-is.
      Parameters:
        `mapType` - the target type, which needs to be a sub-interface of Map or a concrete Map class
      See Also:
        `Map`, `HashMap`, `TreeMap`, `LinkedHashMap`

    - #### CustomMapEditor

          public CustomMapEditor(Class mapType,
                         boolean nullAsEmptyMap)

      Create a new CustomMapEditor for the given target type.

      If the incoming value is of the given type, it will be used as-is. If it is a different Map type or an array, it will be converted to a default implementation of the given Map type. If the value is anything else, a target Map with that single value will be created.

      The default Map implementations are: TreeMap for SortedMap, and LinkedHashMap for Map.

      Parameters:
        `mapType` - the target type, which needs to be a sub-interface of Map or a concrete Map class
        `nullAsEmptyMap` - ap whether to convert an incoming `null` value to an empty Map (of the appropriate type)
      See Also:
        `Map`, `TreeMap`, `LinkedHashMap`

  - ### Method Detail

    - #### setAsText

          public void setAsText(String text)
                         throws IllegalArgumentException

      Convert the given text value to a Map with a single element.
      Specified by:
        `setAsText` in interface `PropertyEditor`
      Overrides:
        `setAsText` in class `PropertyEditorSupport`
      Throws:
        `IllegalArgumentException`

    - #### setValue

          public void setValue(Object value)

      Convert the given value to a Map of the target type.
      Specified by:
        `setValue` in interface `PropertyEditor`
      Overrides:
        `setValue` in class `PropertyEditorSupport`

    - #### createMap

          protected Map createMap(Class mapType,
                      int initialCapacity)

      Create a Map of the given type, with the given initial capacity (if supported by the Map type).
      Parameters:
        `mapType` - a sub-interface of Map
        `initialCapacity` - the initial capacity
      Returns:
        the new Map instance

    - #### alwaysCreateNewMap

          protected boolean alwaysCreateNewMap()

      Return whether to always create a new Map, even if the type of the passed-in Map already matches.

      Default is "false"; can be overridden to enforce creation of a new Map, for example to convert elements in any case.

      See Also:
        `convertKey(java.lang.Object)`, `convertValue(java.lang.Object)`

    - #### convertKey

          protected Object convertKey(Object key)

      Hook to convert each encountered Map key. The default implementation simply returns the passed-in key as-is.

      Can be overridden to perform conversion of certain keys, for example from String to Integer.

      Only called if actually creating a new Map! This is by default not the case if the type of the passed-in Map already matches. Override `alwaysCreateNewMap()` to enforce creating a new Map in every case.

      Parameters:
        `key` - the source key
      Returns:
        the key to be used in the target Map
      See Also:
        `alwaysCreateNewMap()`

    - #### convertValue

          protected Object convertValue(Object value)

      Hook to convert each encountered Map value. The default implementation simply returns the passed-in value as-is.

      Can be overridden to perform conversion of certain values, for example from String to Integer.

      Only called if actually creating a new Map! This is by default not the case if the type of the passed-in Map already matches. Override `alwaysCreateNewMap()` to enforce creating a new Map in every case.

      Parameters:
        `value` - the source value
      Returns:
        the value to be used in the target Map
      See Also:
        `alwaysCreateNewMap()`

    - #### getAsText

          public String getAsText()

      This implementation returns `null` to indicate that there is no appropriate text representation.
      Specified by:
        `getAsText` in interface `PropertyEditor`
      Overrides:
        `getAsText` in class `PropertyEditorSupport`