Difference between revisions of "EclipseLink/UserGuide/MOXy/Type Level/Mapping to a Type or Element/Default Root Element"

From Eclipsepedia

Jump to: navigation, search
m (Replacing page with 'Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/type_level001.htm')
 
(6 intermediate revisions by 2 users not shown)
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">
+
@XmlRootElement
+
public class Customer {
+
  private String name;
+
  private Address billingAddress;
+
  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:
+
 
+
<source lang="java">
+
@XmlRootElement(name="my-customer")
+
public class Customer {
+
  private String name;
+
  private Address billingAddress;
+
  private Address shippingAddress;
+
 
+
  ...
+
}
+
</source>
+
 
+
<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>
+
 
+
{{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/Mapping to a Type or Element|Mapping to a Type or Element]]
+
|next=[[EclipseLink/UserGuide/MOXy/Type Level/Setting Up Namespace Information|Setting Up Namespace Information]]
+
|up=[[EclipseLink/UserGuide/MOXy/Mapping to a Type or Element|Mapping to a Type or Element]]
+
|version=2.2.0
+
}}
+

Latest revision as of 09:49, 8 November 2012

Please see http://www.eclipse.org/eclipselink/documentation/2.4/moxy/type_level001.htm