# ElementMap
Date: 2013-02-18

## org.simpleframework.xml
Annotation Type ElementMap

    @Retention(value=RUNTIME)
    public @interface ElementMap

The `ElementMap` annotation represents a method or field that is a `Map` for storing key value pairs. The map object deserialized is typically of the same type as the field. However, a `class` attribute can be used to override the field type, however the type must be assignable.

        <map class="java.util.HashMap">
           <entry key="one">value one</entry>
           <entry key="two">value two</entry>
           <entry key="three">value three</entry>
        </map>

If a `class` attribute is not provided and the type or the field or method is abstract, a suitable match is searched for from the maps available from the Java collections framework. This annotation can support both primitive and composite values and keys enabling just about any configuration to be used.

        <map class="java.util.HashMap">
           <entry key="1">
              <value>value one</value>
           </entry>
           <entry key="2">
              <value>value two</value>
           </entry>
           <entry key="3">
              <value>value three</value>
           </entry>
        </map>

The above XML is an example of the output for an composite value object. Composite and primitive values can be used without any specified attributes, in such a case names for primitives are the names of the objects they represent. Also, if desired these default names can be overridden using the provided attributes making the resulting XML entirely configurable.

Author:
  Niall Gallagher

Optional Element Summary
`boolean` `attribute` Represents whether the key value is to be an attribute or an element.
`boolean` `data` This is used to determine whether the element data is written in a CDATA block or not.
`boolean` `empty` This is used to determine if an optional field or method can remain null if it does not exist.
`java.lang.String` `entry` This is used to provide a the name of the entry XML element that wraps the key and value elements.
`boolean` `inline` Determines whether the element list is inlined with respect to the parent XML element.
`java.lang.String` `key` This is used to provide a key XML element for each of the keys within the map.
`java.lang.Class` `keyType` Represents the type of key the element map contains.
`java.lang.String` `name` This represents the name of the XML element.
`boolean` `required` Determines whether the element is required within the XML document.
`java.lang.String` `value` This is used to provide a value XML element for each of the values within the map.
`java.lang.Class` `valueType` Represents the type of value the element map contains.

### name

    public abstract java.lang.String name

  This represents the name of the XML element. Annotated fields can optionally provide the name of the element. If no name is provided then the name of the annotated field or method will be used in its place. The name is provided if the field or method name is not suitable as an XML element name. Also, if the list is inline then this must not be specified.

  Returns:
    the name of the XML element this represents
  Default:
    ""

### entry

    public abstract java.lang.String entry

  This is used to provide a the name of the entry XML element that wraps the key and value elements. If specified the entry value specified will be used instead of the default name of the element. This is used to ensure the resulting XML is configurable to the requirements of the generated XML.

  Returns:
    this returns the entry XML element for each entry
  Default:
    ""

### value

    public abstract java.lang.String value

  This is used to provide a value XML element for each of the values within the map. This essentially wraps the entity to be serialized such that there is an extra XML element present. This can be used to override the default names of primitive values, however it can also be used to wrap composite values.

  Returns:
    this returns the value XML element for each value
  Default:
    ""

### key

    public abstract java.lang.String key

  This is used to provide a key XML element for each of the keys within the map. This essentially wraps the entity to be serialized such that there is an extra XML element present. This can be used to override the default names of primitive keys, however it can also be used to wrap composite keys.

  Returns:
    this returns the key XML element for each key
  Default:
    ""

### keyType

    public abstract java.lang.Class keyType

  Represents the type of key the element map contains. This type is used to deserialize the XML entry key from the map. The object typically represents the deserialized type, but can represent a subclass of the type deserialized as determined by the `class` attribute value for the map. If this is not specified then the type can be determined from the generic parameter of the annotated `Map` object.

  Returns:
    the type of the entry key deserialized from the XML
  Default:
    void.class

### valueType

    public abstract java.lang.Class valueType

  Represents the type of value the element map contains. This type is used to deserialize the XML entry value from the map. The object typically represents the deserialized type, but can represent a subclass of the type deserialized as determined by the `class` attribute value for the map. If this is not specified then the type can be determined from the generic parameter of the annotated `Map` object.

  Returns:
    the type of the entry value deserialized from the XML
  Default:
    void.class

### attribute

    public abstract boolean attribute

  Represents whether the key value is to be an attribute or an element. This allows the key to be embedded within the entry XML element allowing for a more compact representation. Only primitive key objects can be represented as an attribute. For example a `java.util.Date` or a string could be represented as an attribute key for the generated XML.

  Returns:
    true if the key is to be inlined as an attribute
  Default:
    false

### required

    public abstract boolean required

  Determines whether the element is required within the XML document. Any field marked as not required will not have its value set when the object is deserialized. If an object is to be serialized only a null attribute will not appear as XML.

  Returns:
    true if the element is required, false otherwise
  Default:
    true

### data

    public abstract boolean data

  This is used to determine whether the element data is written in a CDATA block or not. If this is set to true then the text is written within a CDATA block, by default the text is output as escaped XML. Typically this is useful when this annotation is applied to an array of primitives, such as strings.

  Returns:
    true if entries are to be wrapped in a CDATA block
  Default:
    false

### inline

    public abstract boolean inline

  Determines whether the element list is inlined with respect to the parent XML element. An inlined element list does not contain an enclosing element. It is simple a sequence of elements that appear one after another within an element. As such an inline element list must not have a name.

  Returns:
    this returns true if the element list is inline
  Default:
    false

### empty

    public abstract boolean empty

  This is used to determine if an optional field or method can remain null if it does not exist. If this is false then the optional element is given an empty map. This is a convenience attribute which avoids having to check if the element is null before providing it with a suitable default instance.

  Returns:
    false if an optional element is always instantiated
  Default:
    true