<?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 work with wrapper elements around collections</title>
    <abstract/>
    <status>Final</status>
  </properties>
  <body>
    <title>How to work with wrapper elements around collections</title>
    <header/>

    <section title="Intended Audience">

        <p>
            How to work with wrapper elements around collections.
        </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 class that holds a collection of objects of the 
            same type, and you want to wrap the XML produced for the 
            collection members with an additional XML artefact, then 
            read on.
        </p>
           
    </section>

    <section title="Java entities">
    
        <p>For example, assume you have the following Java class <tt>Foo</tt>:</p>

        <code-panel><![CDATA[
package com.example;
import java.util.Collection;

public class Foo {
    private String name;
    private Collection children;

    public Foo(){}
    public Foo(String name){
        setName(name);
    }
    public Collection getChildren() {
        return children;
    }
    public void setChildren(Collection children) {
        this.children = children;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
}
]]></code-panel>
        
    </section>
    
    <section title="Required XML output and XML schema">
    
        <p>and you want to have Castor generate XML which looks like:</p>
        
        <code-panel>
&lt;foo:foo xmlns:foo="http://example.com/foo" name="foo"&gt;
    <b><font color="red">&lt;foo:children&gt;</font></b>
        &lt;foo:foo name="foo1" /&gt;
        &lt;foo:foo name="foo2" /&gt;
    <b><font color="red">&lt;/foo:children&gt;</font></b>
&lt;/foo:foo&gt;</code-panel>

        <p>
            where the structure of the output is defined by the following 
            XML schema:
        </p>
        
        <code-panel>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;schema xmlns="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://example.com/foo"
    xmlns:tns="http://example.com/foo" elementFormDefault="qualified"&gt;
    &lt;complexType name="fooType"&gt;
        &lt;sequence&gt;
            &lt;element name="children" minOccurs="0"&gt;
                &lt;complexType&gt;
                    &lt;sequence&gt;
                        &lt;element name="foo" type="tns:fooType"
                            maxOccurs="unbounded"&gt;
                        &lt;/element&gt;
                    &lt;/sequence&gt;
                &lt;/complexType&gt;
            &lt;/element&gt;
        &lt;/sequence&gt;
        &lt;attribute name="name"&gt;&lt;/attribute&gt;
    &lt;/complexType&gt;
&lt;/schema&gt;</code-panel>

    </section>

    <section title="Mapping file">

        <p>then you would use a mapping like where the <tt>location</tt> attribute
           on the field mapping for <tt>children</tt> defines the wrapper
           XML artifact to be used:</p>

        <code-panel>
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Mapping DTD Version 1.0//EN"
                         "http://castor.org/mapping.dtd"&gt;
&lt;mapping&gt;
    &lt;class name="com.example.Foo" auto-complete="false"&gt;
        &lt;map-to xml="foo" ns-uri="http://example.com/foo" ns-prefix="foo" /&gt;
        &lt;field name="name" type="java.lang.String"&gt;
            &lt;bind-xml name="name" node="attribute" /&gt;
        &lt;/field&gt;
        &lt;field name="children" collection="collection" type="com.example.Foo"&gt;
            &lt;bind-xml name="foo" <b><font color="red">location="children"</font></b> /&gt;
        &lt;/field&gt;
    &lt;/class&gt;
&lt;/mapping&gt;
</code-panel>
    
    </section>

  </body>
</document>


