Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Introduction to XML Projects (ELUG)"

m (XML Project Concepts)
m
Line 1: Line 1:
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Introduction to XML Projects (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Introduction to XML Projects (ELUG)|Related Topics]]</div>
 
 
This section provides an overview of XML projects and their components.
 
This section provides an overview of XML projects and their components.
  
Line 9: Line 8:
  
 
==XML Project Concepts==
 
==XML Project Concepts==
 
 
Use an XML project for nontransactional, nonpersistent (in-memory) conversions between Java objects and XML documents using JAXB (see [[#EclipseLink Support for Java Architecture for XML Binding (JAXB)|EclipseLink Support for Java Architecture for XML Binding (JAXB)]] and [[#JAXB Validation|JAXB Validation]]). The Workbench provides complete support for creating XML projects.
 
Use an XML project for nontransactional, nonpersistent (in-memory) conversions between Java objects and XML documents using JAXB (see [[#EclipseLink Support for Java Architecture for XML Binding (JAXB)|EclipseLink Support for Java Architecture for XML Binding (JAXB)]] and [[#JAXB Validation|JAXB Validation]]). The Workbench provides complete support for creating XML projects.
  
Line 15: Line 13:
  
 
This table describes the components of an XML project.
 
This table describes the components of an XML project.
 
  
 
<span id="Table 52-1"></span>
 
<span id="Table 52-1"></span>
Line 38: Line 35:
 
Mappings
 
Mappings
 
| headers="r4c1-t2 r1c2-t2" align="left" |
 
| headers="r4c1-t2 r1c2-t2" align="left" |
For more information, see the following:
+
For more information, see [[XML Mappings (ELUG)|XML Mappings]].
* [[XML Mappings (ELUG)|XML Mappings]]
+
 
|}
 
|}
  
Line 49: Line 45:
  
 
===EclipseLink Support for Java Architecture for XML Binding (JAXB)===
 
===EclipseLink Support for Java Architecture for XML Binding (JAXB)===
 
 
JAXB provides a standard Java object-to-XML API. For more information, see <tt>http://java.sun.com/xml/jaxb/index|l</tt>.
 
JAXB provides a standard Java object-to-XML API. For more information, see <tt>http://java.sun.com/xml/jaxb/index|l</tt>.
  
Line 63: Line 58:
  
 
====Working with JAXB-Specific Generated Files====
 
====Working with JAXB-Specific Generated Files====
 
 
The EclipseLink JAXB compiler generates the following JAXB-specific files from your XSD:
 
The EclipseLink JAXB compiler generates the following JAXB-specific files from your XSD:
 
 
* [[#Content and Element Interfaces|Content and Element Interfaces]]
 
* [[#Content and Element Interfaces|Content and Element Interfaces]]
 
* [[#Implementation Classes|Implementation Classes]]
 
* [[#Implementation Classes|Implementation Classes]]
Line 73: Line 66:
 
The JAXB runtime uses these files as specified by the JAXB specification.
 
The JAXB runtime uses these files as specified by the JAXB specification.
  
All JAXB-specific files are generated in the output directory you define, and in the subdirectories implied by the target package name you define. For more information about EclipseLink JAXB binding compiler options, see [[Creating%20an%20XML%20Project%20(ELUG)|Creating an XML Project from an XML Schema]].
+
All JAXB-specific files are generated in the output directory you define, and in the subdirectories implied by the target package name you define. For more information about EclipseLink JAXB binding compiler options, see [[Creating%20an%20XML%20Project%20(ELUG)|#Creating an XML Project from an XML SchemaCreating an XML Project from an XML Schema]].
  
 
Before you compile your generated classes, be sure to configure your IDE classpath to include <tt><</tt>''<tt>ECLIPSELINK_HOME</tt>''<tt>>\lib\xml.jar</tt>. For an example, see [[Using%20an%20Integrated%20Development%20Environment%20(ELUG)|Using an Integrated Development Environment]].
 
Before you compile your generated classes, be sure to configure your IDE classpath to include <tt><</tt>''<tt>ECLIPSELINK_HOME</tt>''<tt>>\lib\xml.jar</tt>. For an example, see [[Using%20an%20Integrated%20Development%20Environment%20(ELUG)|Using an Integrated Development Environment]].
Line 80: Line 73:
  
 
=====Content and Element Interfaces=====
 
=====Content and Element Interfaces=====
 
 
All interfaces are named according to the content, element, or implementation <tt>name</tt> attribute defined in the XSD.
 
All interfaces are named according to the content, element, or implementation <tt>name</tt> attribute defined in the XSD.
  
Line 86: Line 78:
  
 
=====Implementation Classes=====
 
=====Implementation Classes=====
 
 
All implementation classes are named according to the content, element, or implementation <tt>name</tt> attribute defined in the XSD and a suffix of <tt>Impl</tt>.
 
All implementation classes are named according to the content, element, or implementation <tt>name</tt> attribute defined in the XSD and a suffix of <tt>Impl</tt>.
  
Line 94: Line 85:
  
 
=====ObjectFactory Class=====
 
=====ObjectFactory Class=====
 
 
The <tt>ObjectFactory</tt> class provides an instance factory method for each content and element interface. For example, given an element interface <tt>ItemsImpl</tt>, there would be an instance factory method in the <tt>ObjectFactory</tt> class with the following signature:
 
The <tt>ObjectFactory</tt> class provides an instance factory method for each content and element interface. For example, given an element interface <tt>ItemsImpl</tt>, there would be an instance factory method in the <tt>ObjectFactory</tt> class with the following signature:
 
  public ItemsImpl createItemsImpl() throws javax.xml.bind.JAXBException
 
  public ItemsImpl createItemsImpl() throws javax.xml.bind.JAXBException
Line 105: Line 95:
  
 
=====JAXB Properties File=====
 
=====JAXB Properties File=====
 
 
The JAXB properties file is named <tt>jaxb.properties</tt> and it contains a single entry that defines the <tt>javax.xml.bind.context.factory</tt> property with a value equal to the fully qualified class name of the EclipseLink implementation of <tt>JAXBContext</tt><nowiki>:</nowiki>
 
The JAXB properties file is named <tt>jaxb.properties</tt> and it contains a single entry that defines the <tt>javax.xml.bind.context.factory</tt> property with a value equal to the fully qualified class name of the EclipseLink implementation of <tt>JAXBContext</tt><nowiki>:</nowiki>
 
  javax.xml.bind.context.factory=org.eclipse.persistence.ox.jaxb.JAXBContextFactory
 
  javax.xml.bind.context.factory=org.eclipse.persistence.ox.jaxb.JAXBContextFactory
 +
 +
  
 
====Working with EclipseLink-Specific Generated Files====
 
====Working with EclipseLink-Specific Generated Files====
 
 
The EclipseLink JAXB compiler generates the following EclipseLink-specific files from your XSD:
 
The EclipseLink JAXB compiler generates the following EclipseLink-specific files from your XSD:
 
 
* [[#EclipseLink Sessions XML File|EclipseLink Sessions XML File]]
 
* [[#EclipseLink Sessions XML File|EclipseLink Sessions XML File]]
 
* [[#EclipseLink Project XML File|EclipseLink Project XML File]]
 
* [[#EclipseLink Project XML File|EclipseLink Project XML File]]
Line 120: Line 109:
 
You use these files to customize the EclipseLink metadata that corresponds to the generated JAXB-specific objects.
 
You use these files to customize the EclipseLink metadata that corresponds to the generated JAXB-specific objects.
  
All EclipseLink-specific files are generated in a subdirectory, named <tt>eclipselink</tt>, of the output directory you specify (see [[Creating%20an%20XML%20Project%20(ELUG)|Creating an XML Project from an XML Schema]]).
+
All EclipseLink-specific files are generated in a subdirectory, named <tt>eclipselink</tt>, of the output directory you specify (see [[Creating%20an%20XML%20Project%20(ELUG)#Creating an XML Project from an XML Schema|Creating an XML Project from an XML Schema]]).
  
 
The <tt>eclipselink</tt> subdirectory is organized as this figure illustrates.
 
The <tt>eclipselink</tt> subdirectory is organized as this figure illustrates.
Line 133: Line 122:
  
 
=====EclipseLink Sessions XML File=====
 
=====EclipseLink Sessions XML File=====
 
 
In the generated <tt>sessions.xml</tt> file, the <tt>name</tt> element is the name of the context path and the <tt>project-xml</tt> element is the name of the generated project XML file.
 
In the generated <tt>sessions.xml</tt> file, the <tt>name</tt> element is the name of the context path and the <tt>project-xml</tt> element is the name of the generated project XML file.
  
Line 155: Line 143:
  
  
As in any EclipseLink project, the EclipseLink session is your primary facade to the EclipseLink XML API (see [[#Using EclipseLink JAXB Compiler Generated Files at Run Time]]).
+
As in any EclipseLink project, the EclipseLink session is your primary facade to the EclipseLink XML API (see [[#|Using EclipseLink JAXB Compiler Generated Files at Run Time]]).
  
  
  
 
=====EclipseLink Project XML File=====
 
=====EclipseLink Project XML File=====
 
+
The project XML file is named the same as the XSD, but with a file extension of <tt>xml</tt>. In the [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]] figure, the name of the generated project XML file is <tt>purchaseOrder.xml</tt>.
The project XML file is named the same as the XSD, but with a file extension of <tt>xml</tt>. In [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]], the name of the generated project XML file is <tt>purchaseOrder.xml</tt>.
+
  
 
The project XML file contains a descriptor and associated mappings for each content, element, and implementation class.
 
The project XML file contains a descriptor and associated mappings for each content, element, and implementation class.
Line 168: Line 155:
  
 
=====Workbench Project=====
 
=====Workbench Project=====
 
+
The Workbench project is written to a subdirectory as the [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]] figure illustrates. This subdirectory contains a Workbench project file named with the same name as the XSD, but with a file extension of <tt>mwp</tt> and the required <tt>descriptor</tt> and <tt>class</tt> subdirectories. In the [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]] figure, the Workbench project is named <tt>purchaseOrder.mwp</tt>.
The Workbench project is written to a subdirectory as [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]] illustrates. This subdirectory contains a Workbench project file named with the same name as the XSD, but with a file extension of <tt>mwp</tt> and the required <tt>descriptor</tt> and <tt>class</tt> subdirectories. In [[#Figure 52-1|JAXB Binding Compiler Generated Files and Directories]], the Workbench project is named <tt>purchaseOrder.mwp</tt>.
+
  
 
Optionally, you can use this Workbench project to customize the generated descriptors and mappings and reexport the project XML file.
 
Optionally, you can use this Workbench project to customize the generated descriptors and mappings and reexport the project XML file.
Line 176: Line 162:
  
 
=====Typesafe Enumeration Converter Amendment Method DescriptorAfterLoads Class=====
 
=====Typesafe Enumeration Converter Amendment Method DescriptorAfterLoads Class=====
 
+
The EclipseLink JAXB compiler will generate a single class called <tt>DescriptorAfterLoads</tt> if any implementation class contains a mapping to a type safe enumeration (see [[Introduction%20to%20Mappings%20(ELUG)#Mappings and JAXB Typesafe Enumerations|Mappings and JAXB Typesafe Enumerations]]).
The EclipseLink JAXB compiler will generate a single class called <tt>DescriptorAfterLoads</tt> if any implementation class contains a mapping to a type safe enumeration (see [[Introduction%20to%20Mappings%20(ELUG)|Mappings and JAXB Typesafe Enumerations]]).
+
  
 
The EclipseLink JAXB compiler will update this <tt>DescriptorAfterLoads</tt> class with a descriptor amendment method called <tt>amend<</tt>''<tt>ImplementationClassName</tt>''<tt>></tt> for each implementation class that contains a mapping to a typesafe enumeration. The amendment method sets an instance of <tt>JAXBTypesafeEnumConverter</tt> on each mapping that maps to a typesafe enumeration in that implementation class.
 
The EclipseLink JAXB compiler will update this <tt>DescriptorAfterLoads</tt> class with a descriptor amendment method called <tt>amend<</tt>''<tt>ImplementationClassName</tt>''<tt>></tt> for each implementation class that contains a mapping to a typesafe enumeration. The amendment method sets an instance of <tt>JAXBTypesafeEnumConverter</tt> on each mapping that maps to a typesafe enumeration in that implementation class.
  
The Workbench project that the EclipseLink JAXB compiler creates (see [[#Workbench Projec]t]) configures the implementation class descriptor with this amendment method. You can open the generated Workbench project and regenerate deployment XML without losing support for this feature.
+
The Workbench project that the EclipseLink JAXB compiler creates (see [[#Workbench Project|Workbench Project]]) configures the implementation class descriptor with this amendment method. You can open the generated Workbench project and regenerate deployment XML without losing support for this feature.
 +
 
 +
 
  
 
====Using EclipseLink JAXB Compiler Generated Files at Run Time====
 
====Using EclipseLink JAXB Compiler Generated Files at Run Time====
 
 
At run time, you can access the EclipseLink JAXB compiler-generated files by doing the following:
 
At run time, you can access the EclipseLink JAXB compiler-generated files by doing the following:
 
 
* Using EclipseLink <tt>XMLContext</tt> (see [[#How to Use EclipseLink XML Context|How to Use EclipseLink XML Context]])
 
* Using EclipseLink <tt>XMLContext</tt> (see [[#How to Use EclipseLink XML Context|How to Use EclipseLink XML Context]])
 
* Using EclipseLink <tt>XMLBinder</tt> (see [[#How to Use EclipseLink XML Binder|How to Use EclipseLink XML Binder]])
 
* Using EclipseLink <tt>XMLBinder</tt> (see [[#How to Use EclipseLink XML Binder|How to Use EclipseLink XML Binder]])
Line 194: Line 179:
  
 
=====How to Use EclipseLink XML Context=====
 
=====How to Use EclipseLink XML Context=====
 
 
EclipseLink provides an <tt>XMLContext</tt> class with which you can create instances of EclipseLink <tt>XMLMarshaller</tt>, <tt>XMLUnmarshaller</tt>, <tt>XMLBinder</tt> (see [[#How to Use EclipseLink XML Binder|How to Use EclipseLink XML Binder]]), and <tt>XMLValidator</tt>.
 
EclipseLink provides an <tt>XMLContext</tt> class with which you can create instances of EclipseLink <tt>XMLMarshaller</tt>, <tt>XMLUnmarshaller</tt>, <tt>XMLBinder</tt> (see [[#How to Use EclipseLink XML Binder|How to Use EclipseLink XML Binder]]), and <tt>XMLValidator</tt>.
  
Line 202: Line 186:
 
<ol>
 
<ol>
 
<li> Configure your application classpath to include your domain object class files (see [[#Working with JAXB-Specific Generated Files|Working with JAXB-Specific Generated Files]]) and the EclipseLink runtime.</li>
 
<li> Configure your application classpath to include your domain object class files (see [[#Working with JAXB-Specific Generated Files|Working with JAXB-Specific Generated Files]]) and the EclipseLink runtime.</li>
<li> Acquire the session manager (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring the Session Manager]]).</li>
+
<li> Acquire the session manager (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring the Session Manager|Acquiring the Session Manager]]).</li>
<li> Use the session manager to acquire your XML session using the <tt>sessions.xml</tt> file you generated with the EclipseLink JAXB compiler (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Session from the Session Manage]r]).</li>
+
<li> Use the session manager to acquire your XML session using the <tt>sessions.xml</tt> file you generated with the EclipseLink JAXB compiler (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring a Session from the Session Manager|Acquiring a Session from the Session Manager]]).</li>
 
<li> Get the XML project instance from the session:  
 
<li> Get the XML project instance from the session:  
 
<div class="pre">
 
<div class="pre">
Line 233: Line 217:
 
Using the <tt>XMLContext</tt> <tt>getDocumentPreservationPolicy</tt> method, you can retrieve this context's document preservation policy in a form of the <tt>DocumentPreservationPolicy</tt> object. This object's API lets you specify the position of newly added to the node elements, as well as disable the addition of new elements.
 
Using the <tt>XMLContext</tt> <tt>getDocumentPreservationPolicy</tt> method, you can retrieve this context's document preservation policy in a form of the <tt>DocumentPreservationPolicy</tt> object. This object's API lets you specify the position of newly added to the node elements, as well as disable the addition of new elements.
  
=====How to Use EclipseLink XML Binder=====
 
  
 +
 +
=====How to Use EclipseLink XML Binder=====
 
<tt>XMLBinder</tt> is a run-time class that allows you to preserve a document that you have unmarshalled, as well as to resynchronize that document with the unmarshalled objects at any time.
 
<tt>XMLBinder</tt> is a run-time class that allows you to preserve a document that you have unmarshalled, as well as to resynchronize that document with the unmarshalled objects at any time.
  
Line 310: Line 295:
  
 
=====How to Use JAXB Context=====
 
=====How to Use JAXB Context=====
 
+
You can create an instance of <tt>JAXBContext</tt> using the target package name you selected for your files (see [[#Working with JAXB-Specific Generated Files|Working with JAXB-Specific Generated Files]]) as the context path, as the [[#Example 52-6|Using the Context Path]] example shows. This example assumes that you configure your application classpath to include your domain object class files.
You can create an instance of <tt>JAXBContext</tt> using the target package name you selected for your files (see [[#Working with JAXB-Specific Generated Files]]) as the context path, as [[#Example 52-6|Using the Context Path]] shows. This example assumes that you configure your application classpath to include your domain object class files.
+
  
 
The <tt>JAXBContext</tt> object is thread-safe.
 
The <tt>JAXBContext</tt> object is thread-safe.
Line 322: Line 306:
 
  PurchaseOrder purchaseOrder =  
 
  PurchaseOrder purchaseOrder =  
 
     (PurchaseOrder)unmarshaller.unmarshal(new File("purchaseOrder.xml"));
 
     (PurchaseOrder)unmarshaller.unmarshal(new File("purchaseOrder.xml"));
 +
 +
  
 
===JAXB Validation===
 
===JAXB Validation===
 
 
EclipseLink can validate both complete object trees and subtrees against the XML schema that was used to generate the implementation classes. In addition, EclipseLink will validate both root objects (objects that correspond to the root element of the XML document) and nonroot objects against the schema used to generate the object's implementation class.
 
EclipseLink can validate both complete object trees and subtrees against the XML schema that was used to generate the implementation classes. In addition, EclipseLink will validate both root objects (objects that correspond to the root element of the XML document) and nonroot objects against the schema used to generate the object's implementation class.
  
 
When validating an object tree, EclipseLink performs the following checks (in order):
 
When validating an object tree, EclipseLink performs the following checks (in order):
 
 
# Check that element appears in the document at the specified location.
 
# Check that element appears in the document at the specified location.
 
# If '''maxOccurs''' or '''minOccurs''' is specified, check number of elements.
 
# If '''maxOccurs''' or '''minOccurs''' is specified, check number of elements.
Line 360: Line 344:
 
[[Category: Draft]]
 
[[Category: Draft]]
 
[[Category: Concept]]
 
[[Category: Concept]]
 +
[[Category: XML]]

Revision as of 09:12, 17 December 2007

This section provides an overview of XML projects and their components.

For information on project concepts and features common to more than one type of EclipseLink projects, see Introduction to Projects.


XML Project Concepts

Use an XML project for nontransactional, nonpersistent (in-memory) conversions between Java objects and XML documents using JAXB (see EclipseLink Support for Java Architecture for XML Binding (JAXB) and JAXB Validation). The Workbench provides complete support for creating XML projects.

The EclipseLink runtime performs XML data conversion based on one or more XML schemas. In an XML project, Workbench directly references schemas in the deployment XML, and exports mappings configured with respect to the schemas you specify. For information on how to use Workbench with XML schemas, see Using XML Schemas. For information on how EclipseLink supports XML namespaces, see XML Namespaces Overview.

This table describes the components of an XML project.

XML Project Components

Component Supported Types

Data Source

None

Descriptors

For more information, see Descriptor Concepts.

Mappings

For more information, see XML Mappings.


In an XML project, you do not use EclipseLink queries and expressions.


EclipseLink Support for Java Architecture for XML Binding (JAXB)

JAXB provides a standard Java object-to-XML API. For more information, see http://java.sun.com/xml/jaxb/index%7Cl.

EclipseLink provides an extra layer of functions on top of JAXB. It allows for the creation and subsequent manipulation of mappings (in the form of a Workbench project) from an existing object model, without requiring the recompilation of the JAXB object model.

An essential component of this function is the EclipseLink JAXB compiler. Using the EclipseLink JAXB compiler, you can generate both a EclipseLink XML project and JAXB-compliant object model classes from your XML schema.

The EclipseLink JAXB compiler simplifies JAXB application development with EclipseLink by automatically generating (see Creating an XML Project from an XML Schema) both the required JAXB files (see Working with JAXB-Specific Generated Files) and the EclipseLink files ( Working with EclipseLink-Specific Generated Files) from your XML schema (XSD) document.

For more information on using the JAXB and EclipseLink-specific run-time classes, see Using EclipseLink JAXB Compiler Generated Files at Run Time.


Working with JAXB-Specific Generated Files

The EclipseLink JAXB compiler generates the following JAXB-specific files from your XSD:

The JAXB runtime uses these files as specified by the JAXB specification.

All JAXB-specific files are generated in the output directory you define, and in the subdirectories implied by the target package name you define. For more information about EclipseLink JAXB binding compiler options, see #Creating an XML Project from an XML SchemaCreating an XML Project from an XML Schema.

Before you compile your generated classes, be sure to configure your IDE classpath to include <ECLIPSELINK_HOME>\lib\xml.jar. For an example, see Using an Integrated Development Environment.


Content and Element Interfaces

All interfaces are named according to the content, element, or implementation name attribute defined in the XSD.


Implementation Classes

All implementation classes are named according to the content, element, or implementation name attribute defined in the XSD and a suffix of Impl.

The generated implementation classes are simple domain classes, with private attributes for each JAXB property, and public get and set methods that return or set attribute values.


ObjectFactory Class

The ObjectFactory class provides an instance factory method for each content and element interface. For example, given an element interface ItemsImpl, there would be an instance factory method in the ObjectFactory class with the following signature:

public ItemsImpl createItemsImpl() throws javax.xml.bind.JAXBException

The ObjectFactory class also provides a dynamic instance factory allocator with the following signature:

public static Object newInstance(Class javaContentInterface)
    throws javax.xml.bind.JAXBException


JAXB Properties File

The JAXB properties file is named jaxb.properties and it contains a single entry that defines the javax.xml.bind.context.factory property with a value equal to the fully qualified class name of the EclipseLink implementation of JAXBContext:

javax.xml.bind.context.factory=org.eclipse.persistence.ox.jaxb.JAXBContextFactory


Working with EclipseLink-Specific Generated Files

The EclipseLink JAXB compiler generates the following EclipseLink-specific files from your XSD:

You use these files to customize the EclipseLink metadata that corresponds to the generated JAXB-specific objects.

All EclipseLink-specific files are generated in a subdirectory, named eclipselink, of the output directory you specify (see Creating an XML Project from an XML Schema).

The eclipselink subdirectory is organized as this figure illustrates.


JAXB Binding Compiler Generated Files and Directories

JAXB Binding Compiler Generated Files and Directories


EclipseLink Sessions XML File

In the generated sessions.xml file, the name element is the name of the context path and the project-xml element is the name of the generated project XML file.

This example shows a typical sessions.xml file where the context path is examples.ox.model.


Typical Generated sessions.xml File

<?xml version="1.0" encoding="US-ASCII"?>
<eclipselink-sessions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="file://xsd/sessions_10_0_3.xsd" version="0">
    <session xsi:type="database-session">
        <name>customer_example</name>
        <primary-project xsi:type="xml">purchaseOrder.xml</primary-project>

        <login xsi:type="xml-login">
            <platform-class>org.eclipse.persistence.ox.platform.SAXPlatform</platform-class>
        </login>
    </session>
</eclipselink-sessions>


As in any EclipseLink project, the EclipseLink session is your primary facade to the EclipseLink XML API (see Using EclipseLink JAXB Compiler Generated Files at Run Time).


EclipseLink Project XML File

The project XML file is named the same as the XSD, but with a file extension of xml. In the JAXB Binding Compiler Generated Files and Directories figure, the name of the generated project XML file is purchaseOrder.xml.

The project XML file contains a descriptor and associated mappings for each content, element, and implementation class.


Workbench Project

The Workbench project is written to a subdirectory as the JAXB Binding Compiler Generated Files and Directories figure illustrates. This subdirectory contains a Workbench project file named with the same name as the XSD, but with a file extension of mwp and the required descriptor and class subdirectories. In the JAXB Binding Compiler Generated Files and Directories figure, the Workbench project is named purchaseOrder.mwp.

Optionally, you can use this Workbench project to customize the generated descriptors and mappings and reexport the project XML file.


Typesafe Enumeration Converter Amendment Method DescriptorAfterLoads Class

The EclipseLink JAXB compiler will generate a single class called DescriptorAfterLoads if any implementation class contains a mapping to a type safe enumeration (see Mappings and JAXB Typesafe Enumerations).

The EclipseLink JAXB compiler will update this DescriptorAfterLoads class with a descriptor amendment method called amend<ImplementationClassName> for each implementation class that contains a mapping to a typesafe enumeration. The amendment method sets an instance of JAXBTypesafeEnumConverter on each mapping that maps to a typesafe enumeration in that implementation class.

The Workbench project that the EclipseLink JAXB compiler creates (see Workbench Project) configures the implementation class descriptor with this amendment method. You can open the generated Workbench project and regenerate deployment XML without losing support for this feature.


Using EclipseLink JAXB Compiler Generated Files at Run Time

At run time, you can access the EclipseLink JAXB compiler-generated files by doing the following:


How to Use EclipseLink XML Context

EclipseLink provides an XMLContext class with which you can create instances of EclipseLink XMLMarshaller, XMLUnmarshaller, XMLBinder (see How to Use EclipseLink XML Binder), and XMLValidator.

The XMLContext is thread-safe. For example, if multiple threads accessing the same XMLContext object request an XMLMarshaller, each will receive their own instance of XMLMarshaller, so any state that the XMLMarshaller maintains will be unique to that process. By using the XMLContext, you can use EclipseLink XML in multithreaded architectures, such as the binding layer for Web services.

To use the EclipseLink XMLContext, do the following:

  1. Configure your application classpath to include your domain object class files (see Working with JAXB-Specific Generated Files) and the EclipseLink runtime.
  2. Acquire the session manager (see Acquiring the Session Manager).
  3. Use the session manager to acquire your XML session using the sessions.xml file you generated with the EclipseLink JAXB compiler (see Acquiring a Session from the Session Manager).
  4. Get the XML project instance from the session:
    Project myProject = session.getProject();
    
  5. Create a EclipseLink XML context instance with the project:
    XMLContext context = new XMLContext(myProject);
    
  6. Use the XMLContext to create a EclipseLink XMLMarshaller, XMLUnmarshaller, XMLBinder, and XMLValidator:
    XMLMarshaller marshaller = context.createMarshaller();
    marshaller.marshal(myObject, outputStream);
    marshaller.setFormattedOutput(true);
    
    XMLUnmarshaller unmarshaller = context.createUnmarshaller();
    Employee emp = (Employee)unmarshaller.unmarshal(new File("employee.xml"));
    
    XMLBinder binder = context.createBinder();
    Address add = (Address)binder.unmarshal(myElement);
    
    XMLValidator validator = context.createValidator();
    boolean isValid = validator.validate(emp);
    

Using the XMLContext getDocumentPreservationPolicy method, you can retrieve this context's document preservation policy in a form of the DocumentPreservationPolicy object. This object's API lets you specify the position of newly added to the node elements, as well as disable the addition of new elements.


How to Use EclipseLink XML Binder

XMLBinder is a run-time class that allows you to preserve a document that you have unmarshalled, as well as to resynchronize that document with the unmarshalled objects at any time.


Note: This functionality is based on the JAXB binder API (javax.xml.bind.Binder<XmlNode>). This is an addition to the design-time method of document preservation.


When the XMLBinder unmarshalls XML nodes into mapping objects, and then performs an update operation, it preserves not only the order of elements, but also the comments from an original XML document using the cached value. This way, both the returned node and the cached node are identical and reflect the preserved document. When adding new elements, EclipseLink XMLBinder places them at the correct location in the node.

When unmarshalling a document that contains only unmapped content, setting some values and then marshalling, the XMLBinder adds new elements after existing unmapped data, such as comments and processing instructions. In the case of unmapped elements, if the information is available from the schema, then use the schema ordering.

This example demonstrates how you can unmarshall a document using an instance of an XMLBinder.


Unmarshalling a Document Using XMLBinder

XMLContext conext = new XMLContext(myProject);
XMLBinder binder = context.createBinder();
Employee emp = (Employee) binder.unmarshal(myDocument);


In the preceding example, emp is the root object that was unmarshalled from the provided document. The binder maintains references to the original XML document as well as objects generated during the unmarshall operation.

This example demonstrates how you can make changes to the object (Employee) and update the XML document using an instance of an XMLBinder.


Making Changes to an Object and to Updating XML Using XMLBinder

...
emp.setPhoneNumber("123-4567");
Node updatedNode = binder.updateXML(emp);


In the preceding example, the updatedNode object is the updated version of the original XML node from which this employee was unmarshalled. In addition, the binder's cached node, which you can retrieve using binder.getXMLNode(emp), is updated. Note that the cached node preserves the document, including comments, as the following example shows:

<employee>

   <!--comment1 -->
      <name>John Smith </name>
      <phone-number>123-4567</phone-number>
   <!--comment2 -->
</employee>

This example demonstrates how you can obtain an associated node for a subobject (Address) of the Employee using an instance of an XMLBinder.

Obtaining an Associated Node Using XMLBinder

...
Address addr = emp.getAddress();
Node addressNode = binder.getXMLNode(addr);


In the preceding example, the returned node (addressNode) is the XML node in the original XML document that was used to build this employee's Address object.

This example demonstrates how you can make changes to an XML node and update objects (Address) of the Employee using an instance of an XMLBinder.

Making Changes to an XML Node and Updating Objects Using XMLBinder

...
addressNode.setAttribute("apt-no", "1527");
Address updatedAddressNode = binder.updateObject(addressNode);


In the preceding example, the address returned from the binder operation is the original Address object created during the unmarshall operation, but now it contains the updated apartment number information from the XML document.


How to Use JAXB Context

You can create an instance of JAXBContext using the target package name you selected for your files (see Working with JAXB-Specific Generated Files) as the context path, as the Using the Context Path example shows. This example assumes that you configure your application classpath to include your domain object class files.

The JAXBContext object is thread-safe.


Using the Context Path

JAXBContext jaxbContext = JAXBContext.newInstance("examples.ox.model");
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
PurchaseOrder purchaseOrder = 
    (PurchaseOrder)unmarshaller.unmarshal(new File("purchaseOrder.xml"));


JAXB Validation

EclipseLink can validate both complete object trees and subtrees against the XML schema that was used to generate the implementation classes. In addition, EclipseLink will validate both root objects (objects that correspond to the root element of the XML document) and nonroot objects against the schema used to generate the object's implementation class.

When validating an object tree, EclipseLink performs the following checks (in order):

  1. Check that element appears in the document at the specified location.
  2. If maxOccurs or minOccurs is specified, check number of elements.
  3. If type is specified, check that element value satisfies the type constraints.
  4. If a fixed value is specified, check that the element value matches it.
  5. If restrictions (length, patterns, enumerations, and so on) are specified, check that the element value satisfies it.
  6. If an ID type is specified during a validateRoot operation, check that the ID value is unique in the document.
  7. If an IDREF type is specified during a validateRoot operation, check that the ID referenced exists in the document.

If validation errors are encountered, EclipseLink stops validating the object tree and creates a ValidationEvent object, according to the JAXB specification. If an error occurs in a subobject, EclipseLink will not validate further down that object's subtree.

For more information on using EclipseLink XML to perform validation, see Using EclipseLink JAXB Compiler Generated Files at Run Time.

For additional information on JAXB and validation, refer to the JAXB specification at http://java.sun.com/xml/jaxb/.







Copyright Statement

Back to the top