View source for Configuring an XML Descriptor (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Configuring an XML Descriptor (ELUG)|Related Topics]]</div>

For information on how to create XML descriptors, see [[Creating%20an%20XML%20Descriptor%20(ELUG)|Creating an XML Descriptor]].

This table lists the default configurable options for an XML descriptor.

<span id="Table 57-1"></span>
{| class="RuleFormalMax" dir="ltr" title="Configuration Options for XML Descriptors" summary="This table lists the configurable options common XML Descriptors Basic and Advanced and indicates if the option can be configured with the Workbench, Java, or both." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
|- align="left" valign="top"
! id="r1c1-t2" align="left" valign="bottom" | '''Option to Configure'''
! id="r1c2-t2" align="left" valign="bottom" | '''EclipseLink Workbench'''
! id="r1c3-t2" align="left" valign="bottom" | '''Java'''
|- align="left" valign="top"
| id="r2c1-t2" headers="r1c1-t2" align="left" |
[[Using%20Workbench%20(ELUG)#How to Configure XML Schema Namespace|XML schema namespace]]
| headers="r2c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r2c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r3c1-t2" headers="r1c1-t2" align="left" |
[[Using%20Workbench%20(ELUG)#How to Configure an XML Schema Reference|XML schema reference]]
| headers="r3c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r3c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r4c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Schema Context for an XML Descriptor|Schema context]]
| headers="r4c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r4c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r5c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring for Complex Type of anyType|Complex type of anyType]]
| headers="r5c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r5c1-t2 r1c3-t2" align="left" |
[[Image:unsupport.gif|Unsupported.]]
|- align="left" valign="top"
| id="r6c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Default Root Element|Default root element]]
| headers="r6c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r6c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r7c1-t2" headers="r1c1-t2" align="left" |
[[#Configuring Document Preservation|Document preservation]]
| headers="r7c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r7c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r8c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Descriptor Comments|Comments]]
| headers="r8c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r8c1-t2 r1c3-t2" align="left" |
[[Image:unsupport.gif|Unsupported.]]
|- align="left" valign="top"
| id="r9c1-t2" headers="r1c1-t2" align="left" |
[[Using%20Workbench%20(ELUG)#How to Configure Classes|Classes]]
| headers="r9c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r9c1-t2 r1c3-t2" align="left" |
[[Image:unsupport.gif|Unsupported.]]
|- align="left" valign="top"
| id="r10c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor|Inheritance for a child class descriptor]]
| headers="r10c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported.]]
| headers="r10c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported.]]
|- align="left" valign="top"
| id="r11c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inheritance for a Parent (Root) Descriptor|Inheritance for a parent descriptor]]
| headers="r11c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r11c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r12c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Inherited Attribute Mapping in a Subclass|Inherited attribute mapping in a subclass]]
| headers="r12c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported.]]
| headers="r12c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported.]]
|- align="left" valign="top"
| id="r13c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Instantiation Policy|Instantiation policy]]
| headers="r13c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r13c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r14c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring Copy Policy|Copy policy]]
| headers="r14c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r14c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r15c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Descriptor%20(ELUG)#Configuring a Descriptor|Amendment methods]]
| headers="r15c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r15c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|- align="left" valign="top"
| id="r16c1-t2" headers="r1c1-t2" align="left" |
[[Configuring%20a%20Mapping%20(ELUG)#Configuring a Mapping|Mapping]]
| headers="r16c1-t2 r1c2-t2" align="left" |
[[Image:support.gif|Supported]]
| headers="r16c1-t2 r1c3-t2" align="left" |
[[Image:support.gif|Supported]]
|}


For more information, see [[Introduction%20to%20XML%20Descriptors%20(ELUG)|Introduction to XML Descriptors]].



==Configuring Schema Context for an XML Descriptor==
The Workbench uses the schema context to associate the XML descriptor reference class with a simple or complex type in one of the schemas associated with the XML project (see [[Using%20Workbench%20(ELUG)#How to Configure an XML Schema Reference|How to Configure an XML Schema Reference]]). This allows the Workbench to display the appropriate attributes available for mapping in that context.

You must configure the schema context for an XML descriptor regardless of whether or not you are using the Workbench.

The EclipseLink runtime uses the schema context to validate XML fragments.


===How to Configure Schema Context for an XML Descriptor Using Workbench===
To associate an XML descriptor with a specific schema complex type, use this procedure:
# Select an XML descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br><span id="Figure 57-1"></span>''''' Descriptor Info Tab, Schema Context Option'''''<br>[[Image:schmctx.gif|Descriptor Info Tab, Schema Context Option]]
# Complete the Schema Context field on the tab.
# Click '''Browse''' to select the schema element to associate with this descriptor. For more information, see [[#Choosing a Schema Context|Choosing a Schema Context]].

See Also:
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]


====Choosing a Schema Context====
#Use the Choose Schema Context dialog box to select a specific schema element (such as when mapping an element).<br><span id="Figure 57-2"></span><br>''''' Choose Schema Context Dialog Box'''''<br>[[Image:schcontx.gif|Choose Schema Context Dialog Box]]
#Select a schema element and click '''OK'''.


===How to Configure Schema Context for an XML Descriptor Using Java===
To configure an XML descriptor with a schema context using Java, create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]) that uses <tt>XMLSchemaReference</tt> method <tt>setSchemaContext</tt>, as this example shows.

<span id="Example 57-1"></span>
''''' Configuring Schema Context'''''
<source lang="java">
 public void addToDescriptor(ClassDescriptor descriptor) {
     descriptor.getSchemaReference().setSchemaContext(xPath);
 }
</source>


==Configuring for Complex Type of anyType==
This attribute applies only to Workbench. Use this option to solve "No schema context is specified" problems (see [[Using%20Workbench%20(ELUG)#How to Use the Problems Window|How to Use the Problems Window]]) for an XML descriptor that does not represent an element in your XML schema.

In general, Workbench assumes that every XML descriptor must have a schema context (see [[#Configuring Schema Context for an XML Descriptor|Configuring Schema Context for an XML Descriptor]]). However, if a class in your project does not relate to an element in your schema, then it does not have a schema context.

Consider the schema that this exmaple shows:


<span id="Example 57-2"></span>
''''' Schema Using xsd:anyType'''''
<source lang="xml">
 <?xml version="1.0" encoding="UTF-8"?>
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 
     <xsd:element name="customer" type="customer-type"/>
     <xsd:complexType name="customer-type">
         <xsd:sequence>
             <xsd:element name="contact-method" type="xsd:anyType"/>
         </xsd:sequence>
     </xsd:complexType>
 
     <xsd:element name="address">
         <xsd:complexType>
             <xsd:sequence>
                 <xsd:element name="street" type="xsd:string"/>
                 <xsd:element name="city" type="xsd:string"/>
             </xsd:sequence>
 
         </xsd:complexType>
     </xsd:element>
     <xsd:element name="phone-number" type="xsd:string"/>
 </xsd:schema>
</source>

Because element <tt>contact-method</tt> is of type <tt>xsd:anyType</tt>, your project requires a class to represent that type, such as class <tt>AnyTypeImpl</tt> shown in the [[#Figure 57-3|Class Representing xsd:anyType]] figure. Because this class does not relate to any complex type in your schema, it has no schema context. In this example, you would select this option for the <tt>AnyTypeImpl</tt> class.

<br>
<span id="Figure 57-3"></span>
''''' Class Representing xsd:anyType'''''

[[Image:cmplxtp.gif|Class Representing xsd:anyType]]


For more information, see [[Introduction%20to%20XML%20Mappings%20(ELUG)#xs:any and xs:anyType Support|xs:any and xs:anyType Support]].


===How to Configure Complex Type of anyType Using Workbench===
To specify that the descriptor represents a complex type of <tt>anyType</tt>, use this procedure:
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Descriptor Info Tab, Complex Type "anyType" Option<br>'''''[[Image:drcmplxa.gif|Descriptor Info Tab, Complex Type "anyType" Option]]
#Select the '''Descriptor Represents Complex Type "anyType"''' option to specify this descriptor as the root element.



==Configuring Default Root Element==
The default root element is the name that EclipseLink uses for the root element when marshalling objects for this descriptor to, and unmarshalling from, an XML document. Descriptors used only in composite relationship mappings do not require a default root element.

For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Default Root Element|Default Root Element]].


===How to Configure Default Root Element Using Workbench===
To specify a schema element as the default root element for the descriptor, use this procedure:
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Descriptor Info Tab, Default Root Option'''''<br>[[Image:docroot.gif|Descriptor Info Tab, Default Root Option]]
#Select the '''Default Root Element''' option to specify this descriptor as the root element.
#Click '''Browse''' to select the schema element to identify as the root element for this descriptor. See [[#Choosing a Root Element|Choosing a Root Element]] for more information.

See Also:
: [[#Configuring Default Root Element|Configuring Default Root Element]]


====Choosing a Root Element====
Use the Choose Root Element dialog box to select a specific root element.

''''' Choose Root Element Dialog Box'''''

[[Image:rootelem.gif|Choose Root Element Dialog Box]]

Select the root element and click '''OK'''.



==Configuring Document Preservation==
EclipseLink lets you preserve any "extra" data in your XML source that is not required to map to an object model (such as comments, processing instructions, or unmapped elements).

This permits round-tripping from XML to objects and back to XML without losing any data.


===How to Configure Document Preservation Using Workbench===
To preserve the entire XML source document, use this procedure:
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor.
# Click the '''Descriptor Info''' tab. The Descriptor Info tab appears.<br>'''''Descriptor Info Tab, Preserve Document Option'''''<br>[[Image:preserve.gif|Descriptor Info Tab, Preserve Document Option]]
#Select the '''Preserve Document''' option to maintain any extra information from the source XML document that EclipseLink does not require (such as comments).

See Also:
: [[#Configuring Document Preservation|Configuring Document Preservation]]
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]


===How to Configure Document Preservation Using Java===
To configure an XML descriptor to maintain any extra information from the source XML document that EclipseLink does not require (such as comments) using Java, create a descriptor amendment method (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]) that configures the descriptor using <tt>XMLDescriptor</tt> method <tt>setShouldPreserveDocument</tt>.


----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Task]]
[[Category: XML]]