|
|
Line 1: |
Line 1: |
− | {{EclipseLink_UserGuide
| + | Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/type_level001.htm |
− | |eclipselink=y
| + | |
− | |eclipselinktype=MOXy
| + | |
− | |info=y
| + | |
− | |toc=y
| + | |
− | |api=y
| + | |
− | |apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlRootElement.html XmlRootElement]
| + | |
− | }}
| + | |
− | | + | |
− | = Default Root Element =
| + | |
− | | + | |
− | At least one of your mapped classes must have a default root element defined. This tells EclipseLink what the top-level root of your XML document will be. Consider the <tt>Customer</tt> and <tt>Address</tt> classes shown in this example:
| + | |
− | | + | |
− | [[Image:Defaultrootelement.png]]<br><br>
| + | |
− | | + | |
− | These classes correspond to the XML schema shown in this example. The schema contains a top-level element of type "<tt>customer-type</tt>", therefore our <tt>Customer</tt> class will need to have a default root element specified.
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | <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>
| + | |
− | </source>
| + | |
− | | + | |
− | The following example shows how to annotate your Java class to specify a default root element. All that is needed is the standard JAXB <tt>@XmlRootElement</tt> annotation.
| + | |
− | | + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | | + | |
− | @XmlRootElement
| + | |
− | public class Customer {
| + | |
− | private String name;
| + | |
− | | + | |
− | @XmlElement(name="billing-address")
| + | |
− | private Address billingAddress;
| + | |
− | | + | |
− | @XmlElement(name="shipping-address")
| + | |
− | private Address shippingAddress;
| + | |
− | | + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | The example below shows how specify a default root element in EclipseLink's OXM metadata format.
| + | |
− | | + | |
− | <source lang="xml">
| + | |
− | ...
| + | |
− | <java-type name="Customer">
| + | |
− | <xml-root-element/>
| + | |
− | <java-attributes>
| + | |
− | <xml-element java-attribute="name"/>
| + | |
− | <xml-element java-attribute="billingAddress" name="billing-address"/>
| + | |
− | <xml-element java-attribute="shippingAddress" name="shipping-address"/>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | ...
| + | |
− | </source>
| + | |
− | | + | |
− | <br><br>
| + | |
− | | + | |
− | == Customizing the Default Root Element ==
| + | |
− | | + | |
− | In the above example, our class is called <tt>Customer</tt>, and our root element name in XML is <tt>customer</tt>. By default, when <tt>@XmlRootElement</tt> is specified, the name of the class has its first letter lower-cased, and this is set as the root element name. If, however, the element name in XML is different from the Java class name, a <tt>name</tt> attribute can be included in the annotation or OXM metadata:
| + | |
− | | + | |
− | '''''Java Annotations'''''
| + | |
− | <source lang="java">
| + | |
− | package example;
| + | |
− | | + | |
− | import javax.xml.bind.annotation.*;
| + | |
− | | + | |
− | @XmlRootElement(name="my-customer")
| + | |
− | public class Customer {
| + | |
− | private String name;
| + | |
− | | + | |
− | @XmlElement(name="billing-address")
| + | |
− | private Address billingAddress;
| + | |
− | | + | |
− | @XmlElement(name="shipping-address")
| + | |
− | private Address shippingAddress;
| + | |
− | | + | |
− | ...
| + | |
− | }
| + | |
− | </source>
| + | |
− | | + | |
− | '''''EclipseLink OXM Metadata'''''
| + | |
− | <source lang="xml">
| + | |
− | ...
| + | |
− | <java-type name="Customer">
| + | |
− | <xml-root-element name="my-customer"/>
| + | |
− | <java-attributes>
| + | |
− | <xml-element java-attribute="name"/>
| + | |
− | <xml-element java-attribute="billingAddress" name="billing-address"/>
| + | |
− | <xml-element java-attribute="shippingAddress" name="shipping-address"/>
| + | |
− | </java-attributes>
| + | |
− | </java-type>
| + | |
− | ...
| + | |
− | </source>
| + | |
− | | + | |
− | {{tip||For more information on JAXB name-binding algorithms, see "Appendix D: Binding XML Names to Java Identifiers" of the ''Java Architecture for XML Binding (JAXB) 2.2 Specification''.}}
| + | |
− | | + | |
− | <br><br>
| + | |
− | | + | |
− | == How EclipseLink uses the Default Root Element ==
| + | |
− | | + | |
− | When an instance of the <tt>Customer</tt> class is persisted to XML, the EclipseLink runtime performs the following:
| + | |
− | | + | |
− | * Gets the default root element. The <tt>Customer</tt> class instance corresponds to the root of the XML document. The EclipseLink runtime uses the default root element (<tt>customer</tt>) specified in either annotations or OXM to start the XML document. EclipseLink then uses the mappings on the class to marshal the object's attributes.
| + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <name>...</name>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | * When the EclipseLink runtime encounters an object attribute such as <tt>billingAddress</tt>, it checks the mapping associated with it to determine with what element (<tt>billing-address</tt>) to continue.
| + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <name>...</name>
| + | |
− | <billing-address/>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | * The EclipseLink runtime checks the mapping's reference descriptor (<tt>Address</tt>) to determine what attributes to persist.
| + | |
− | <source lang="xml">
| + | |
− | <customer>
| + | |
− | <name>...</name>
| + | |
− | <billing-address>
| + | |
− | <street>...</street>
| + | |
− | <city>...</city>
| + | |
− | </billing-address>
| + | |
− | </customer>
| + | |
− | </source>
| + | |
− | | + | |
− | | + | |
− | {{EclipseLink_MOXy
| + | |
− | |previous=[[EclipseLink/UserGuide/MOXy/Type Level|Type Level]]
| + | |
− | |next= [[EclipseLink/UserGuide/MOXy/Type Level/Setting Up Namespace Information|Setting Up Namespace Information]]
| + | |
− | }}
| + | |