Package com.emc.documentum.rest.binding

# Annotation Interface SerializableField4XmlList

@Target(FIELD) @Retention(RUNTIME) public @interface SerializableField4XmlList
The annotation defined on a Java List or Array field for custom marshalling and unmarshalling. This annotation is effective only when the field is explicitly marked by annotation `SerializableField` or set as visible by `SerializableType.FieldVisibility`.

Since:
  7.3

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `boolean`
  `asPropBag`
  Specifies the list items to be marshalled as property bag or not.
  `String`
  `itemName`
  Specifies the list item element name within a `List` data type field when the field is marshalled as the property bag.
  `boolean`
  `unwrap`
  Specifies whether to unwrap the list or array items of this field as the direct members of the serializable type.

- ## Element Details

  - ### unwrap

    boolean unwrap
    Specifies whether to unwrap the list or array items of this field as the direct members of the serializable type. When unwrapped, the collection container will be removed and the list items of this field will be promoted upper level to be the direct members of this class.

    Constraints:
    (a) this setting is applied to field of data type `List` and array only
    (b) the data type in the list item must be simple types or complex types annotated with `SerializableType`.
    (c) the element name for the unwrapped list item is determined by `asPropBag()` and `itemName()`.
    (d) the unmarshalling of the unwrapped list or array will be incorrect if the same class has more than one field to unwrap the lists with the same base data type.

    For example, below code marshals the list items as unwrapped.

         {@literal @}SerializableField4XmlList(unwrap=true, itemName="fruit")
         List<Fruit> fruits = Arrays.asList(new Apple("red"), new Orange("yellow"));

    will be marshalled as XML representation:

         <fruit>
           <color>red</color>
         </fruit>
         <fruit>
           <color>yellow</color>
         </fruit>

    For example, below code marshals the list items as property bag.

         {@literal @}SerializableField4XmlList(unwrap=false, itemName="fruit")
         List<Fruit> fruits = Arrays.asList(new Apple("red"), new Orange("yellow"));

    will be marshalled as XML representation:

         <fruits>
           <fruit>
             <color>red</color>
           </fruit>
           <fruit>
             <color>yellow</color>
           </fruit>
         </fruits>

    Returns:
      `true` if the field is to be unwrapped; false for otherwise
    Default:
      false

  - ### asPropBag

    boolean asPropBag
    Specifies the list items to be marshalled as property bag or not.
    For example, below code marshals the list items as property bag. `{@literal @}SerializableField4XmlList(asPropBag=true, itemName="fruit") List<Fruit> fruits = Arrays.asList(new Apple("red"), new Orange("yellow"));` will be marshalled as XML representation:

         <fruits>
           <fruit>
             <color>red</color>
           </fruit>
           <fruit>
             <color>yellow</color>
           </fruit>
         </fruits>

    For example, below code does not marshal the list items as property bag. `{@literal @}SerializableField4XmlList(asPropBag=false) List<Fruit> fruits = Arrays.asList(new Apple("red"), new Orange("yellow"));` will be marshalled as XML representation:

         <fruits>
           <apple>
             <color>red</color>
           </apple>
           <orange>
             <color>yellow</color>
           </orange>
         </fruits>

    The simple data type list field is always marshalled as the property bag, so this attribute is only applied to the data type of the list items that are complex type annotated by `SerializableType`.

    Returns:
      `true` if the list is wrapped as property bag; false for otherwise
    Default:
      false

  - ### itemName

    String itemName
    Specifies the list item element name within a `List` data type field when the field is marshalled as the property bag. The default is 'item'. For example, below code

         {@literal @}SerializableField4XmlList(itemName="profile")
         List<String> profiles = Arrays.asList("dev", "product");

         will be marshalled as XML representation:

         <profiles>
           <profile>dev</profile>
           <profile>product</profile>
         </profiles>

    This attribute is not effective when `asPropBag()` = `false`.

    Returns:
      the defined property bag name in the wrapped list
    Default:
      "item"