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

    <section title="Intended Audience">

        <p>Anyone who wants to wrap a collection with a wrapper element.</p>
        
        <p>This document helps people to get familiar with the basic concepts
           and shows an example.</p>

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

        <p>None.</p>

    </section>

    <section title="Basic concept">
        
        <p>When you have a field which is a list collection, and you want for each
           element of the list collection to be encapsulated in a containing element,
           then set container="false" in the field element for the list collection. By
           setting this attribute Castor recognizes that you want an element wrapping
           the members of the list.</p>

        <p>By default Castor treats collections as "containers". Containers to Castor
           are simple objects whose only purpose is to hold other objects. Containers
           are not considered "first-class" objects and therefore have no direct XML
           representation. By setting container="false", you are telling Castor that
           the collection is not be treated as a container, but rather a first class
           object which should have an XML-representation.</p>
           
    </section>

    <section title="Java entities">
        <p>For example, if you have the following two classes:</p>

        <code-panel><![CDATA[
package org.castor.example;

import java.util.ArrayList;
import java.util.List;


public class Cart {

    private List<Item> itemsList = new ArrayList<Item>();
        
    public List<Item> getItemsList() {
        return this.itemsList;
    }
    
    public void addItem(Item item) {
        this.itemsList.add(item);
    }
}]]></code-panel>
        
        <code-panel><![CDATA[
package org.castor.example;

public class Item {

    private Integer count;
    private String name;
    
    public Integer getCount() {
        return this.count;
    }
        
    public void setCount(Integer count) {
        this.count = count;
    }

    public String getName() {
        return this.name;
    }
    
    public void setName(String name) {
        this.name = name;
    }
}]]></code-panel>
    </section>

    <section title="Required XML output">
        
        <p>and you want to have Castor generate XML which looks like:</p>

        <code-panel><![CDATA[
<cart>
   <items-list>
       <item>
           <name>broccoli</name>
           <count>1</count>
       </item>
       <item>
           <name>orange</name>
           <count>4</count>
       </item>
   </items-list>
</cart>]]></code-panel>

    </section>

    <section title="Mapping file">

        <p>then you would use a mapping like:</p>

        <code-panel><![CDATA[
<class name="org.castor.example.Cart"
       auto-complete="true">
    <field name="itemsList"
           collection="arraylist"
           type="org.castor.example.Item"
           container="false">
        <bind-xml name="items-list"/>
    </field>
</class>]]></code-panel>
    
    </section>

  </body>
</document>
