XmlElementWrapper (Java Platform SE 8 )
Keywords: javax.xml.bind.annotation.XmlElementWrapper class
Date: 2015-05-24

javax.xml.bind.annotation

## Annotation Type XmlElementWrapper

-     @Retention(value=RUNTIME)
       @Target(value={FIELD,METHOD})
      public @interface XmlElementWrapper

  Generates a wrapper element around XML representation. This is primarily intended to be used to produce a wrapper XML element around collections. The annotation therefore supports two forms of serialization shown below.

          //Example: code fragment
            int[] names;

          // XML Serialization Form 1 (Unwrapped collection)
          <names> ... </names>
          <names> ... </names>

          // XML Serialization Form 2 ( Wrapped collection )
          <wrapperElement>
             <names> value-of-item </names>
             <names> value-of-item </names>
             ....
          </wrapperElement>

  The two serialized XML forms allow a null collection to be represented either by absence or presence of an element with a nillable attribute.

  Usage

  The `@XmlElementWrapper` annotation can be used with the following program elements:

  - JavaBean property
  - non static, non transient field

  The usage is subject to the following constraints:

  - The property must be a collection property
  - This annotation can be used with the following annotations: `XmlElement`, `XmlElements`, `XmlElementRef`, `XmlElementRefs`, `XmlJavaTypeAdapter`.

  See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

  Since:
    JAXB2.0
  See Also:
    `XmlElement`, `XmlElements`, `XmlElementRef`, `XmlElementRefs`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `name` Name of the XML wrapper element.
    `String` | `namespace` XML target namespace of the XML wrapper element.
    `boolean` | `nillable` If true, the absence of the collection is represented by using `xsi:nil='true'`.
    `boolean` | `required` Customize the wrapper element declaration to be required.

- - ### Element Detail

    - #### name

          public abstract String name

      Name of the XML wrapper element. By default, the XML wrapper element name is derived from the JavaBean property name.
      Default:
        "##default"

  - - #### namespace

          public abstract String namespace

      XML target namespace of the XML wrapper element.

      If the value is "##default", then the namespace is determined as follows:

      1. If the enclosing package has `XmlSchema` annotation, and its `elementFormDefault` is `QUALIFIED`, then the namespace of the enclosing class.
      2. Otherwise "" (which produces unqualified element in the default namespace.
      Default:
        "##default"

  - - #### nillable

          public abstract boolean nillable

      If true, the absence of the collection is represented by using `xsi:nil='true'`. Otherwise, it is represented by the absence of the element.
      Default:
        false

  - - #### required

          public abstract boolean required

      Customize the wrapper element declaration to be required.

      If required() is true, then the corresponding generated XML schema element declaration will have `minOccurs="1"`, to indicate that the wrapper element is always expected.

      Note that this only affects the schema generation, and not the unmarshalling or marshalling capability. This is simply a mechanism to let users express their application constraints better.

      Since:
        JAXB 2.1
      Default:
        false

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.