Package org.simpleframework.xml
Annotation Type ElementMap
-
@Retention(RUNTIME) public @interface ElementMap
TheElementMap
annotation represents a method or field that is aMap
for storing key value pairs. The map object deserialized is typically of the same type as the field. However, aclass
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 aclass
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 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.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.
-
-
-
Element Detail
-
name
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
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
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
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
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 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
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 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 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 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 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
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
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
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
-
-