Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Configuring an XML Descriptor (ELUG)"
m (→Configuring Schema Context for an XML Descriptor) |
m |
||
(4 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
+ | [[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__ | <div style="float:right;border:1px solid #000000;padding:5px">__TOC__ | ||
[[Special:Whatlinkshere/Configuring an XML Descriptor (ELUG)|Related Topics]]</div> | [[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. | This table lists the default configurable options for an XML descriptor. | ||
− | |||
<span id="Table 57-1"></span> | <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" | {| 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" | |- align="left" valign="top" | ||
Line 127: | Line 121: | ||
[[Image:support.gif|Supported]] | [[Image:support.gif|Supported]] | ||
|} | |} | ||
− | |||
For more information, see [[Introduction%20to%20XML%20Descriptors%20(ELUG)|Introduction to XML Descriptors]]. | For more information, see [[Introduction%20to%20XML%20Descriptors%20(ELUG)|Introduction to XML Descriptors]]. | ||
+ | |||
+ | |||
==Configuring Schema Context for an XML Descriptor== | ==Configuring Schema Context for an XML Descriptor== | ||
Line 138: | Line 133: | ||
The EclipseLink runtime uses the schema context to validate XML fragments. | The EclipseLink runtime uses the schema context to validate XML fragments. | ||
− | |||
Line 148: | Line 142: | ||
# Click '''Browse''' to select the schema element to associate with this descriptor. For more information, see [[#Choosing a Schema Context|Choosing a Schema Context]]. | # 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]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
− | |||
====Choosing a Schema Context==== | ====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]] | |
− | Use the Choose Schema Context dialog box to select a specific schema element (such as when mapping an element). | + | #Select a schema element and click '''OK'''. |
− | + | ||
− | <span id="Figure 57-2"></span> | + | |
− | ''''' Choose Schema Context Dialog Box''''' | + | |
− | + | ||
− | [[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=== | ===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. | 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> | <span id="Example 57-1"></span> | ||
''''' Configuring Schema Context''''' | ''''' Configuring Schema Context''''' | ||
+ | <source lang="java"> | ||
public void addToDescriptor(ClassDescriptor descriptor) { | public void addToDescriptor(ClassDescriptor descriptor) { | ||
descriptor.getSchemaReference().setSchemaContext(xPath); | descriptor.getSchemaReference().setSchemaContext(xPath); | ||
} | } | ||
+ | </source> | ||
− | |||
− | 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]]) for an XML descriptor that does not represent an element in your XML schema. | + | ==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]]). However, if a class in your project does not relate to an element in your schema, then it does not have a schema context. | + | 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> | <span id="Example 57-2"></span> | ||
''''' Schema Using xsd:anyType''''' | ''''' Schema Using xsd:anyType''''' | ||
+ | <source lang="xml"> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
Line 209: | Line 195: | ||
<xsd:element name="phone-number" type="xsd:string"/> | <xsd:element name="phone-number" type="xsd:string"/> | ||
</xsd:schema> | </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. | |
− | + | ||
− | 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 [[#Figure 57-3|Class Representing xsd:anyType]]. 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> | <br> | ||
Line 221: | Line 206: | ||
− | For more information, see [[Introduction%20to%20XML%20Mappings%20(ELUG)|xs:any and xs:anyType Support]]. | + | 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=== | ===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: | 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. | # 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]] | # 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. | 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]]. | + | For more information, see [[Introduction%20to%20Descriptors%20(ELUG)#Default Root Element|Default Root Element]]. |
− | + | ||
===How to Configure Default Root Element Using Workbench=== | ===How to Configure Default Root Element Using Workbench=== | ||
− | |||
To specify a schema element as the default root element for the descriptor, use this procedure: | 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. | # 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]] | # 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]] | |
− | + | ||
− | + | ||
− | + | ||
− | : [[#Configuring Default Root Element]] | + | |
− | + | ||
====Choosing a Root Element==== | ====Choosing a Root Element==== | ||
− | |||
Use the Choose Root Element dialog box to select a specific root element. | Use the Choose Root Element dialog box to select a specific root element. | ||
Line 271: | Line 246: | ||
==Configuring Document Preservation== | ==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). | 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. | This permits round-tripping from XML to objects and back to XML without losing any data. | ||
− | |||
===How to Configure Document Preservation Using Workbench=== | ===How to Configure Document Preservation Using Workbench=== | ||
− | |||
To preserve the entire XML source document, use this procedure: | To preserve the entire XML source document, use this procedure: | ||
− | |||
# Select a descriptor in the '''Navigator'''. Its properties appear in the Editor. | # 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]] | # 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 Document Preservation]] | + | |
: [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | : [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]] | ||
− | |||
===How to Configure Document Preservation Using Java=== | ===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>. | 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>. | ||
Line 303: | Line 271: | ||
[[Category: EclipseLink User's Guide]] | [[Category: EclipseLink User's Guide]] | ||
− | [[Category: | + | [[Category: Release 1]] |
[[Category: Task]] | [[Category: Task]] | ||
+ | [[Category: XML]] |
Latest revision as of 11:10, 23 July 2012
For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/
Contents
For information on how to create XML descriptors, see Creating an XML Descriptor.
This table lists the default configurable options for an XML descriptor.
Option to Configure | EclipseLink Workbench | Java |
---|---|---|
For more information, see 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 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.
Descriptor Info Tab, Schema Context Option
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.
See Also:
Choosing a Schema Context
- Use the Choose Schema Context dialog box to select a specific schema element (such as when mapping an element).
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 a Descriptor) that uses XMLSchemaReference method setSchemaContext, as this example shows.
Configuring Schema Context
public void addToDescriptor(ClassDescriptor descriptor) { descriptor.getSchemaReference().setSchemaContext(xPath); }
Configuring for Complex Type of anyType
This attribute applies only to Workbench. Use this option to solve "No schema context is specified" problems (see 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). 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:
Schema Using xsd:anyType
<?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>
Because element contact-method is of type xsd:anyType, your project requires a class to represent that type, such as class AnyTypeImpl shown in the 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 AnyTypeImpl class.
Class Representing xsd:anyType
For more information, see 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 anyType, 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.
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 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.
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 for more information.
See Also:
Choosing a Root Element
Use the Choose Root Element dialog box to select a specific root element.
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.
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:
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 a Descriptor) that configures the descriptor using XMLDescriptor method setShouldPreserveDocument.