EclipseLink/UserGuide/MOXy/Relationships/Collections and Maps

EclipseLink MOXy

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Key API

Collections

JAXB contains several annotations to represent collections in XML:

• @XmlElement
• @XmlElementWrapper
• @XmlList
• @XmlList and @XmlAttribute
• @XmlList and @XmlValue

Java Model

To demonstrate the annotations, refer to the following model:

import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    private List<String> emailAddresses;
 
    public Customer() {
        emailAddresses = new ArrayList<String>();
    }
 
    public List<String> getEmailAddresses() {
        return emailAddresses;
    }
 
    public void setEmailAddresses(List<String> emailAddresses) {
        this.emailAddresses = emailAddresses;
    }
 
}

By applying different JAXB annotations, you can produce different XML.

Demo Code

This sample code converts the Customer object to XML.

 
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Marshaller;
 
public class Demo {
 
    public static void main(String[] args) throws Exception {
        JAXBContext jc = JAXBContext.newInstance(Customer.class);
 
        Customer customer = new Customer();
        customer.getEmailAddresses().add("janed@example.com");
        customer.getEmailAddresses().add("jdoe@example.org");
 
        Marshaller marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.marshal(customer, System.out);
    }
}

Default

By default, JAXB marshalls each item in the collection to an XML element:

 
<customer>
    <emailAddresses>janed@example.com</emailAddresses>
    <emailAddresses>jdoe@example.org</emailAddresses>
</customer>

@XmlElement

Use the @XmlElement to control the name of the XML element that a collection item is marshalled to:

 
import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    @XmlElement(name="email-address")
    private List<String> emailAddresses;
 
}

This will produce the following XML:

 
<customer>
    <email-address>janed@example.com</email-address>
    <email-address>jdoe@example.org</email-address>
</customer>

@XmlElementWrapper

Use the @XmlElementWrapper annotation to add a grouping element to organize the collection:

 
import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    @XmlElementWrapper(name="email-addresses")
    @XmlElement(name="email-address")
    private List<String> emailAddresses;
 
}
 
This will produce the following XML:
<source lang="xml">	
<customer>
    <email-addresses>
        <email-address>janed@example.com</email-address>
        <email-address>jdoe@example.org</email-address>
    </email-addresses>
</customer>

@XmlList

Use the @XmlList annotation to represent the collection as space separated text.

import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    @XmlList
    private List<String> emailAddresses;
 
}

This will produce the following XML:

 
<customer>
    <emailAddresses>janed@example.com jdoe@example.org</emailAddresses>
</customer>

@XmlList and @XmlAttribute

Because @XmlList represents a collection in a single piece of text, it can be used with an XML attribute.

 
import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    @XmlList
    @XmlAttribute
    private List<String> emailAddresses;
 
}

This produces the following XML:

 
<customer
    emailAddresses="janed@example.com jdoe@example.org"/>

@XmlList and @XmlValue

Because XmlList represents a collection in a single piece of text, it is also compatible with a single text node.

 
import java.util.*;
import javax.xml.bind.annotation.*;
 
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
 
    @XmlList
    @XmlValue
    private List<String> emailAddresses;
 
}

This produces the following XML:

 
<customer>janed@example.com jdoe@example.org</customer>

Version: 2.2.0 Draft
Other versions...

Special Schema Types	Advanced XML Schema Concepts	Bidirectional Relationships
EclipseLink Home MOXy User Guide: Table of Contents, Search
How to contribute to this guide...