Skip Headers

# Default Root Element

Previous

Next

You configure EIS root descriptors ("Configuring Default Root Element") and XML descriptors ("Configuring Default Root Element") with a default root element so that the TopLink runtime knows the data source data type associated with the class the descriptor describes.

Note: The undefined document root element of a referenced object is ignored during marshalling with an any collection mapping and object mapping.

This section describes what a default root element is and how TopLink uses it.

Consider the `Customer` and `Address` classes and their mappings shown in Example: Customer and Address Classes.

Customer and Address Classes

    Class: Customer
    Default Root: customer
    Attributes and Mappings:
        name:String                Drect Mapping to                name/text()
        billingAddress:Address     Composite Object Mapping to     billing-address
        shippingAddress:Address    Composite Object Mapping to     shipping-address

    Class: Address
    Default Root: address
    Attributes and Mappings:
        street:String              Direct Mapping to               street/text()
        city:String                Direct Mapping to               city/text()

These classes correspond to the XML schema shown in Example: Customer and Address Schema.

Customer and Address Schema

    <xsd:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xsd:complexType name="address-type">
            <xsd:sequence>
                <element name="street" type="xsd:string"/>
                <element name="city" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
        <xsd:element name="customer" type="customer-type"/>
        <xsd:complexType name="customer-type">
            <xsd:sequence>
                <xsd:element name="name" type="xsd:string"/>
                <xsd:element name="billing-address" type="address-type"/>
                <xsd:element name="shipping-address" type="address-type"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:schema>

When an instance of the `Customer` class is persisted to XML, the TopLink runtime performs the following:

1. Gets the default root element.

   The `Customer` class instance corresponds to the root of the XML document. The TopLink runtime uses the default root element specified on the descriptor (`customer`) to start the XML document. TopLink then uses the mappings on the descriptor to marshal the object's attributes:

       <customer>
           <name>…</name>
       </customer>

2. When the TopLink runtime encounters an object attribute such as `billingAddress`, it checks the mapping associated with it to determine with what element (`billing-address`) to continue:

       <customer>
           <name>…</name>
           <billing-address/>
       </customer>

   The TopLink runtime checks the mapping's reference descriptor (`Address`) to determine what attributes to persist:

       <customer>
           <name>…</name>
           <billing-address>
               <street>…</street>
               <city>…</city>
           </billing-address>
       </customer>