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.
 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.
 String key
          This is used to provide a key XML element for each of the keys within the map.
 Class keyType
          Represents the type of key the element map contains.
 String name
          This represents the name of the XML element.
 boolean required
          Determines whether the element is required within the XML document.
 String value
          This is used to provide a value XML element for each of the values within the map.
 Class valueType
          Represents the type of value the element map contains.
 

name

public abstract 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 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 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 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 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 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