# ElementList
Date: 2013-02-18

## org.simpleframework.xml
Annotation Type ElementList

    @Retention(value=RUNTIME)
    public @interface ElementList

The `ElementList` annotation represents a method or field that is a `Collection` for storing entries. The collection 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.

        <list class="java.util.ArrayList">
           <entry name="one"/>
           <entry name="two"/>
           <entry name="three"/>
        </list>

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 collections available from the Java collections framework. This annotation can also compose an inline list of XML elements. An inline list contains no parent or containing element.

        <entry name="one"/>
        <entry name="two"/>
        <entry name="three"/>

The above XML is an example of the output for an inline list of XML elements. In such a list the annotated field or method must not be given a name. Instead the name is acquired from the name of the entry type. For example if the `type` attribute of this was set to an object `example.Entry` then the name of the entry list would be taken as the root name of the object as taken from the `Root` annotation for that object.

Author:
  Niall Gallagher

Optional Element Summary
`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 name of the XML element representing the entry within the list.
`boolean` `inline` Determines whether the element list is inlined with respect to the parent XML element.
`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.Class` `type` Represents the type of object the element list 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 name of the XML element representing the entry within the list. An entry name is optional and is used when the name needs to be overridden. This also ensures that entry, regardless of type has the same root name.

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

### type

    public abstract java.lang.Class type

  Represents the type of object the element list contains. This type is used to deserialize the XML elements from the list. 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 list. If this is not specified then the type can be determined from the generic parameter of the annotated `Collection`.

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

### 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

### 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

### 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 list. 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