Package org.simpleframework.xml
Annotation 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 ElementsModifier and TypeOptional ElementDescriptionboolean
Represents whether the key value is to be an attribute or an element.boolean
This is used to determine whether the element data is written in a CDATA block or not.boolean
This is used to determine if an optional field or method can remain null if it does not exist.This is used to provide a the name of the entry XML element that wraps the key and value elements.boolean
Determines whether the element list is inlined with respect to the parent XML element.This is used to provide a key XML element for each of the keys within the map.Represents the type of key the element map contains.This represents the name of the XML element.boolean
Determines whether the element is required within the XML document.This is used to provide a value XML element for each of the values within the map.Represents the type of value the element map contains.
-
Element Details
-
name
String nameThis 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
String entryThis 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
String valueThis 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
String keyThis 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
Class keyTypeRepresents 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 theclass
attribute value for the map. If this is not specified then the type can be determined from the generic parameter of the annotatedMap
object.- Returns:
- the type of the entry key deserialized from the XML
- Default:
void.class
-
valueType
Class valueTypeRepresents 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 theclass
attribute value for the map. If this is not specified then the type can be determined from the generic parameter of the annotatedMap
object.- Returns:
- the type of the entry value deserialized from the XML
- Default:
void.class
-
attribute
boolean attributeRepresents 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 ajava.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
boolean requiredDetermines 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
boolean dataThis 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
boolean inlineDetermines 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
boolean emptyThis 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
-