JAXB @XmlElementWrapper Example

Java example of JAXB @XmlElementWrapper annotation in detail along with its usage during marshalling and unmarshalling operations.

1. Maven

Start with adding the latest ‘jakarta‘ dependencies for adding the JAXB support (Java 11 onwards).

<dependencies>
  <dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.0</version>
  </dependency>
</dependencies>

<dependencies>
  <dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>4.0.3</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

2. @XmlElementWrapper Annotation

In JAXB, the @XmlElementWrapper annotation generates a wrapper element around a collection of elements.

It can be used in combination with the following annotations:

• @XmlElement
• @XmlElements
• @XmlElementRef
• @XmlElementRefs
• @XmlJavaTypeAdapter

Note that the @XmlElementWrapper annotation can be used with any bean property that is non-static and non-transient.

3. JAXB @XmlElementWrapper Example

Now see a few examples of how using @XmlElementWrapper with @XmlElement changes the XML representations.

3.1. Using @XmlElementWrapper and @XmlElement (Wrapped Collections)

In the following example, we are using both annotations. It shall generate the XML representation containing the wrapper element as well as individual elements.

@XmlRootElement(name = "employee")
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee implements Serializable {
 
  @XmlElementWrapper(name="hobbies")
  @XmlElement(name="hobby")
  private List<String> hobbies;
 
  private Integer id;
  private String firstName;
  private String lastName;
}

The above converts to:

<employee>
    <id>1</id>
    <firstName>Lokesh</firstName>
    <lastName>Gupta</lastName>
 
    <hobbies>
        <hobby>Swimming</hobby>
        <hobby>Playing</hobby>
        <hobby>Karate</hobby>
    </hobbies>
 
</employee>

3.2. Using Only @XmlElementWrapper

Notice when we use only the wrapper element then the wrapper name is used for individual items in the collection as well.

@XmlRootElement(name = "employee")
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee implements Serializable {
 
  @XmlElementWrapper(name="hobbies")
  private List<String> hobbies;
 
  private Integer id;
  private String firstName;
  private String lastName;
}

The above converts to:

<employee>
    <id>1</id>
    <firstName>Lokesh</firstName>
    <lastName>Gupta</lastName>
 
    <hobbies>
        <hobbies>Swimming</hobbies>
        <hobbies>Playing</hobbies>
        <hobbies>Karate</hobbies>
    </hobbies>
 
</employee>

3.3. Not Using @XmlElementWrapper (Unwrapped Collection)

No collection wrapper is generated in this case, and list items are marshaled as part of the parent node.

@XmlRootElement(name = "employee")
@XmlAccessorType(XmlAccessType.FIELD)
public class Employee implements Serializable {
 
  @XmlElement(name="hobby")     
  private List<String> hobbies;
 
  private Integer id;
  private String firstName;
  private String lastName;
}

The above converts to:

<employee>
    <id>1</id>
    <firstName>Lokesh</firstName>
    <lastName>Gupta</lastName>
 
    <hobby>Swimming</hobby>
    <hobby>Playing</hobby>
    <hobby>Karate</hobby>
 
</employee>>

Drop me your questions in the comments section.

Happy Learning !!