<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/howto/how-to-map-a-collection.xml">
  <properties>
    <title>How to map a collection of elements</title>
    <abstract/>
    <status>Final</status>
  </properties>
  <body>
    <title>How to map a collection of elements</title>
    <header/>

    <section title="Intended Audience">

        <p>Anyone who wants to map a collection of elements.</p>
        
        <p>This document helps people to get familiar with the basic concepts
           of mapping and shows an example.</p>

    </section>
    
    <section title="Prerequisites">

        <p>None.</p>

    </section>

    <section title="Basic concept">
        
        <p>Assume you have two classes Order and OrderItem, where an order holds a list
           of order items.</p>
           
        <code-panel>
public class Order {

    private List orderItems;
    private String orderNumber;
    
    public List getOrderItems() {
        return orderItems;
    }
    public void setOrderItems(List orderItems) {
        this.orderItems = orderItems;
    }
    public String getOrderNumber() {
        return orderNumber;
    }
    public void setOrderNumber(String orderNumber) {
        this.orderNumber = orderNumber;
    }
}

public class OrderItem {
    
    private String id;
    private Integer quantity;
    
    public String getId() {
        return id;
    }
    public void setId(String id) {
        this.id = id;
    }
    public Integer getQuantity() {
        return quantity;
    }
    public void setQuantity(Integer quantity) {
        this.quantity = quantity;
    }
}</code-panel>
           
        <p>As shown above, the Order instance has a field 'OrderItems' to hold a list
           of OrderItem instances.</p>
           
    </section>

    <section title="Mapping file">

        <p>Here's the mapping file to instruct Castor XML about the relation of those two 
           classes, Order and OrderItem respectively:</p>

        <code-panel><![CDATA[
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapping>
   <class name="nl.vodafone.castorbinding.demo.Order">
      <map-to xml="Order" />
      <field name="OrderNumber" type="java.lang.String">
         <bind-xml name="orderNumber" node="attribute" />
      </field>
      <field name="OrderItems"
	         type="nl.vodafone.castorbinding.demo.OrderItem"
	         collection="arraylist">
         <bind-xml name="OrderItem" />
      </field>
   </class>
   <class name="nl.vodafone.castorbinding.demo.OrderItem">
      <field name="Id" type="java.lang.String">
         <bind-xml name="id" node="attribute" />
      </field>
      <field name="Quantity" type="java.lang.Integer">
         <bind-xml name="quantity" node="attribute" />
      </field>
   </class>
</mapping>]]></code-panel>
    
    </section>

    <section title="XML output">
        
        <p>Using the Castor XML marshaller with the mapping file shown above, the XML 
           generated by Castor XML might look as follows:</p>

        <code-panel><![CDATA[
<?xml version="1.0"?>
<Order orderNumber="pelssers_20-2-2006_1">
	<OrderItem id="1" quantity="15"/>
    <OrderItem id="3" quantity="20"/>
</Order>]]></code-panel>

    </section>

    <section title="References">

        <ul>
            <li><a href="xml-mapping.html">XML mapping</a></li>
        </ul>
        
    </section>


  </body>
</document>
