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.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
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.

Element Detail

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