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 (Generating TopLink Project and XML Schema Using JAXB 2.0 Annotations)
m
 
(20 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/Introduction to XML Projects (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Introduction to XML Projects (ELUG)|Related Topics]]</div>
Line 38: Line 41:
  
 
In an XML project, you do not use EclipseLink queries and expressions.
 
In an XML project, you do not use EclipseLink queries and expressions.
 +
  
  
Line 47: Line 51:
 
An essential component of this function is the EclipseLink JAXB compiler. Using the EclipseLink JAXB compiler, you can generate both an EclipseLink XML project and JAXB-compliant object model classes from your XML schema.
 
An essential component of this function is the EclipseLink JAXB compiler. Using the EclipseLink JAXB compiler, you can generate both an 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%20an%20XML%20Project%20(ELUG)|Creating an XML Project from an XML Schema]]) both the required JAXB files (see [[#Working with JAXB-Specific Generated Files|Working with JAXB-Specific Generated Files]]) and the EclipseLink files ( [[#Working with EclipseLink-Specific Generated Files|Working with EclipseLink-Specific Generated Files]]) from your XML schema (XSD) document.
+
The EclipseLink JAXB compiler simplifies JAXB application development with EclipseLink by automatically generating (see [[Creating%20an%20XML%20Project%20(ELUG)|Creating an XML Project from an XML Schema]]) the required JAXB files (see [[#Working with JAXB-Specific Generated Files|Working with JAXB-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|Using EclipseLink JAXB Compiler Generated Files at Run Time]].
+
For more information on using the JAXB and EclipseLink-specific run-time classes, see [[#Using EclipseLink JAXB Compiler-Generated Files at Run Time|Using EclipseLink JAXB Compiler-Generated Files at Run Time]].
  
  
====Generating EclipseLink Project and XML Schema Using JAXB 2.0 Annotations====
+
====Generating EclipseLink Project and XML Schema Using JAXB Annotations====
The EclipseLink JAXB compiler generates a EclipseLink project and an XML schema using the following JAXB 2.0 annotations:
+
The EclipseLink JAXB compiler generates a EclipseLink project and an XML schema using the following JAXB annotations:
 
*<tt>XmlRootElement</tt> - Indicates that a class should be mapped to a root-level element in a schema.<br>The element name and namespace are specified in this annotation.<br>This is a class-level annotation.
 
*<tt>XmlRootElement</tt> - Indicates that a class should be mapped to a root-level element in a schema.<br>The element name and namespace are specified in this annotation.<br>This is a class-level annotation.
 
*<tt>XmlElement</tt> - Indicates that a particular attribute on a Java class should be mapped to an XML element in the schema.<br>The name and namespace can be specified by this annotation.<br>This is a field-level annotation.
 
*<tt>XmlElement</tt> - Indicates that a particular attribute on a Java class should be mapped to an XML element in the schema.<br>The name and namespace can be specified by this annotation.<br>This is a field-level annotation.
 +
*<tt>XmlElementRef</tt> - Indicates that a particular attribute on a Java class should be mapped in the schema to an XML element derived from the attribute's type. <br>The name and namespace can be specified by this annotation.<br>This is a field-level annotation.<br>For more information, see [[Introduction%20to%20XML%20Mappings%20(ELUG)#Substitution Groups|Substitution Groups]].
 +
*<tt>XmlElementRefs</tt> - Contains a collection of <tt>XmlElementRef</tt> annotations. <br>This is a field-level annotation.<br>For more information, see [[Introduction%20to%20XML%20Mappings%20(ELUG)#Substitution Groups|Substitution Groups]].
 
*<tt>XmlAttribute</tt> - Indicates that the Java attribute should map to an XML attribute in the schema.<br>Name and namespace should be provided.<br>This is a field-level annotation.
 
*<tt>XmlAttribute</tt> - Indicates that the Java attribute should map to an XML attribute in the schema.<br>Name and namespace should be provided.<br>This is a field-level annotation.
 
*<tt>XmlElementWrapper</tt> - Specifies a wrapper element around another element or attribute.<br>You can use this annotation to create a grouping element around a collection.<br>This is a field-level annotation.
 
*<tt>XmlElementWrapper</tt> - Specifies a wrapper element around another element or attribute.<br>You can use this annotation to create a grouping element around a collection.<br>This is a field-level annotation.
Line 61: Line 67:
 
*<tt>XmlType</tt> - Defines the complex-type for a class.<br>Using this annotation’s <tt>propOrder</tt> property, you can specify the order in which to map elements. The <tt>propOrder</tt> property also determines if the schema should contain a <tt>sequence</tt> or an <tt>all</tt>. Depending on the structure of the class, it will either map to a <tt>ComplexType</tt>, a <tt>SimpleType</tt>, or a <tt>ComplexType</tt> with <tt>SimpleContent</tt>.<br>This is a class-level annotation.
 
*<tt>XmlType</tt> - Defines the complex-type for a class.<br>Using this annotation’s <tt>propOrder</tt> property, you can specify the order in which to map elements. The <tt>propOrder</tt> property also determines if the schema should contain a <tt>sequence</tt> or an <tt>all</tt>. Depending on the structure of the class, it will either map to a <tt>ComplexType</tt>, a <tt>SimpleType</tt>, or a <tt>ComplexType</tt> with <tt>SimpleContent</tt>.<br>This is a class-level annotation.
 
*<tt>XmlTransient</tt> - Indicates that a mapping should not be generated for a particular field.<br>This is a marker annotation.<br>This is a field-level annotation.
 
*<tt>XmlTransient</tt> - Indicates that a mapping should not be generated for a particular field.<br>This is a marker annotation.<br>This is a field-level annotation.
*<tt>XmlSchema</tt> - Specifies the target namespace for a schema.<br>You can also use this annotation to configure namespace prefix mappings with the XmlNs annotation.<br>This is a package-level annotation.
+
*<tt>XmlSchema</tt> - Specifies the target namespace for a schema.<br>You can also use this annotation to configure namespace prefix mappings with the <tt>XmlNs</tt> annotation.<br>This is a package-level annotation.
 
*<tt>XmlNs</tt> - Appears only in an <tt>XmlSchema</tt> annotation to specify namespace-prefix mappings.<br>This is a package-level annotation.
 
*<tt>XmlNs</tt> - Appears only in an <tt>XmlSchema</tt> annotation to specify namespace-prefix mappings.<br>This is a package-level annotation.
*<tt>XmlValue</tt> - Maps an attribute to a text node under the parent class (for example, an Xpath of "text( )").<br>Also indicates that the owning class should map to either a <tt>SimpleType</tt> or a <tt>ComplexType</tt> with <tt>SimpleContent</tt>.
+
*<tt>XmlValue</tt> - Maps an attribute to a text node under the parent class (for example, an Xpath of "text( )").<br>Also indicates that the owning class should map to either a <tt>SimpleType</tt> or a <tt>ComplexType</tt> with <tt>SimpleContent</tt>.<br>This is a field-level annotation.
*<tt>XmlEnum</tt> - Indicates that a JDK1.5 <tt>Enum</tt> type should map to a simple type with enumeration facets in the schema.<br>The base schema type is specified on this annotation.
+
*<tt>XmlEnum</tt> - Indicates that a JDK 1.5 <tt>Enum</tt> type should map to a simple type with enumeration facets in the schema.<br>The base schema type is specified on this annotation.<br>This is a field-level annotation.
*<tt>XmlEnumValue</tt> - Lets you specify the enumeration facets to be used in the schema, if they are to be different from the string values of the <tt>Enum</tt> constants specified in Java.
+
*<tt>XmlEnumValue</tt> - Lets you specify the enumeration facets to be used in the schema, if they are to be different from the string values of the <tt>Enum</tt> constants specified in Java.<br>This is a field-level annotation.
*<tt>XmlAccessorType</tt> - Specifies how the classes’ attributes should be processed.<br>The following are valid values:
+
*<tt>XmlAccessorType</tt> - Specifies how the classes’ attributes should be processed.<br>This is a package- or class-level annotation.<br>The following are valid values:
 
**<tt>FIELD</tt> – Process all the public and/or private fields of the class.
 
**<tt>FIELD</tt> – Process all the public and/or private fields of the class.
 
**<tt>PROPERTY</tt> – Process all the public or private get and set method pairs on the class.
 
**<tt>PROPERTY</tt> – Process all the public or private get and set method pairs on the class.
 
**<tt>PUBLIC_MEMBER</tt> – Process all the public fields and public get and set method pairs on the class.
 
**<tt>PUBLIC_MEMBER</tt> – Process all the public fields and public get and set method pairs on the class.
**<tt>NONE</tt> – Only process members that are annotated with JAXB 2.0 annotations.
+
**<tt>NONE</tt> – Only process members that are annotated with JAXB annotations.
*<tt>XmlAccessorOrder</tt> - Specifies the order in which properties are to be processed.<br>The following are valid values:
+
*<tt>XmlAccessorOrder</tt> - Specifies the order in which properties are to be processed.<br>This is a package- or class-level annotation.<br>The following are valid values:
 
**<tt>DEFAULT</tt>
 
**<tt>DEFAULT</tt>
**<tt>ALPHABETICAL</tt>
+
**<tt>ALPHABETICAL</tt>.
*<tt>XmlSchemaType</tt> - If specified at a property level, indicates the schema type that should be used in schema generation.<br>If used as part of an XmlSchemaTypes annotation, overrides default schema types at a package level.<br>This is a property- or a package-level annotation.
+
*<tt>XmlSchemaType</tt> - If specified at a property level, indicates the schema type that should be used in schema generation.<br>If used as part of an <tt>XmlSchemaTypes</tt> annotation, overrides default schema types at a package level.<br>This is a property- or a package-level annotation.
 
*<tt>XmlSchemaTypes</tt> - Contains a collection of <tt>XmlSchemaType</tt> annotations. Each one specifies a Java class and a XML schema type pair that should be used as a default for this package.<br>This is a package-level annotation.
 
*<tt>XmlSchemaTypes</tt> - Contains a collection of <tt>XmlSchemaType</tt> annotations. Each one specifies a Java class and a XML schema type pair that should be used as a default for this package.<br>This is a package-level annotation.
*<tt>XmlAnyAttribute</tt> - Specifies that a Map property should be mapped to an <tt>xs:any</tt> attribute in the schema. For more information, see XMLAnyAttributeMapping <<insert link>>
+
*<tt>XmlAnyAttribute</tt> - Specifies that a Map property should be mapped to an <tt>xs:any</tt> attribute in the schema. For more information, see [[Introduction%20to%20XML%20Mappings%20(ELUG)#XML Any Attribute Mapping|XML Any Attribute Mapping]].<br>This is a filed-level annotation.
  
For more information, see Chapter 8 of JAXB 2.0 Specification at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html
+
For more information, see Chapter 8 of JAXB Specification at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html
  
  
Line 87: Line 93:
 
The schema is generated from a set of annotated Java classes with support for relationships.
 
The schema is generated from a set of annotated Java classes with support for relationships.
 
|}
 
|}
 +
  
 
====Working with JAXB-Specific Generated Files====
 
====Working with JAXB-Specific Generated Files====
Line 96: Line 103:
 
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 SchemaCreating 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|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 105: Line 112:
  
 
The generated implementation classes are simple domain classes, with private attributes for each JAXB property, and public <tt>get</tt> and <tt>set</tt> methods that return or set attribute values.
 
The generated implementation classes are simple domain classes, with private attributes for each JAXB property, and public <tt>get</tt> and <tt>set</tt> methods that return or set attribute values.
 +
  
 
<!--  
 
<!--  
Line 121: Line 129:
 
  -->
 
  -->
  
 +
<!--
 
====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:
Line 136: Line 145:
  
 
<span id="Figure 52-1"></span>
 
<span id="Figure 52-1"></span>
''''' JAXB Binding Compiler Generated Files and Directories'''''
+
''''' JAXB Binding Compiler-Generated Files and Directories'''''
  
[[Image:jaxbcomp.gif|JAXB Binding Compiler Generated Files and Directories]]
+
[[Image:jaxbcomp.gif|JAXB Binding Compiler-Generated Files and Directories]]
  
  
Line 161: Line 170:
 
  </eclipselink-sessions>
 
  </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]]).
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 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 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 172: Line 180:
  
 
=====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 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>.
  
 
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 183: Line 191:
  
 
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.
 
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 XMLContext|How to Use EclipseLink XMLContext]])
* 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 XMLBinder|How to Use EclipseLink XMLBinder]])
* Using EclipseLink <tt>JAXBContext</tt> (see [[#How to Use JAXB Context|How to Use JAXB Context]])
+
* Using EclipseLink <tt>JAXBContext</tt> (see [[#How to Use JAXBContext|How to Use JAXBContext]])
  
  
 
=====How to Use EclipseLink XMLContext=====
 
=====How to Use EclipseLink XMLContext=====
EclipseLink provides an <tt>org.eclipse.persistence.ox.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>org.eclipse.persistence.ox.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 XMLBinder|How to Use EclipseLink XMLBinder]]), and <tt>XMLValidator</tt>.
  
 
The <tt>XMLContext</tt> is thread-safe. For example, if multiple threads accessing the same <tt>XMLContext</tt> object request an <tt>XMLMarshaller</tt>, each will receive their own instance of <tt>XMLMarshaller</tt>, so any state that the <tt>XMLMarshaller</tt> maintains will be unique to that process. By using the <tt>XMLContext</tt>, you can use EclipseLink XML in multithreaded architectures, such as the binding layer for Web services.
 
The <tt>XMLContext</tt> is thread-safe. For example, if multiple threads accessing the same <tt>XMLContext</tt> object request an <tt>XMLMarshaller</tt>, each will receive their own instance of <tt>XMLMarshaller</tt>, so any state that the <tt>XMLMarshaller</tt> maintains will be unique to that process. By using the <tt>XMLContext</tt>, you can use EclipseLink XML in multithreaded architectures, such as the binding layer for Web services.
 
+
<!--
 
To use the EclipseLink <tt>XMLContext</tt>, do the following:
 
To use the EclipseLink <tt>XMLContext</tt>, do the following:
 
<ol>
 
<ol>
Line 229: Line 237:
 
</li>
 
</li>
 
</ol>
 
</ol>
 +
-->
 +
Create the <tt>XMLContext</tt> using its constructor method and by passing in the session name defined in the <tt>sessions.xml</tt> file, as the following example shows:
 +
XMLContext context = new XMLContext("mysession");
 +
You can also create the <tt>XMLContext</tt> from multiple sessions using a colon separated list of session names, as the following example shows:
 +
XMLContext context = new XMLContext("session1:session2:session3");
 +
Use the <tt>XMLContext</tt> to create an EclipseLink <tt>XMLMarshaller</tt>, <tt>XMLUnmarshaller</tt>, <tt>XMLBinder</tt>, and <tt>XMLValidator</tt>, as follows:
 +
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 <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 Marshal and Unmarshal Events=====
 +
You can provide EclipseLink <tt>XMLMarshaller</tt> and <tt>XMLUnmarshaller</tt> with additional functionality at run time by registering them with a listener to handle specific event callbacks. This allows for extra processing on a business object either immediately before, or immediately after an object is written to or read from XML.
 +
 
 +
There are two types of event callbacks that you can handle in two different ways:
 +
# To handle listener-based callbacks, set an event handler on an instance of <tt>XMLMarshaller</tt> or <tt>XMLUnmarshaller</tt> that implements a required interface, such as <tt>XMLMarshalListener</tt> or <tt>XMLUnmarshalListener</tt>. The events are triggered on the marshaller or unmarshaller's listener for any classes being marshalled or unmarshalled.
 +
# To handle class-specific callbacks, you need to provide the required callback methods on your business objects.
 +
 
 +
 
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' If you specify both the listener and the business object callbacks, the class-specific method will be invoked before the listener event.
 +
|}
 +
 
 +
 
 +
This example shows how to create your custom event listeners.
 +
 
 +
<span id="Example 52-33"></span>
 +
''''' Implementing the EclipseLink XMLMarhsalListener and XMLUnmarhsalListener Interfaces'''''
 +
public class EmployeeMarshalListener implements XMLMarshalListener {
 +
 +
    public void beforeMarshal(Object target) {
 +
        // do something
 +
    }
 +
 +
    public void afterMarshal(Object target) {
 +
        // do something
 +
    }
 +
)
 +
 
 +
 
 +
public class EmployeeUnmarshalListener implements XMLUnmarshalListener {
 +
 +
    public void beforeUnmarshal(Object target, Object parent) {
 +
        // do something
 +
    }
 +
 +
    public void afterUnmarshal(Object target, Object parent) {
 +
        // do something
 +
    }
 +
}
 +
 
 +
The following examples show how to use the listeners in your application.
 +
 
 +
<span id="Example 52-34"></span>
 +
''''' Using the Marshal Listener'''''
 +
...
 +
XMLMarshaller marshaller = context.createMarshaller();
 +
marshaller.setMarshalListener(new EmployeeMarshalListener());
 +
marshaller.marshal(myObject, System.out);
 +
...
 +
 
 +
<span id="Example 52-35"></span>
 +
''''' Using the Unmarshal Listener'''''
 +
...
 +
XMLUnmarshaller unmarshaller = context.createUnmarshaller();
 +
unmarshaller.setUnmarshalListener(new EmployeeUnmarshalListener());
 +
Object myObject = unmarshaller.unmarshal(myFile);
 +
...
 +
 
 +
 
 +
=====How to Use EclipseLink XMLBinder=====
 
<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 247: Line 333:
  
 
This example demonstrates how you can unmarshall a document using an instance of an <tt>XMLBinder</tt>.
 
This example demonstrates how you can unmarshall a document using an instance of an <tt>XMLBinder</tt>.
 
  
 
<span id="Example 52-2"></span>
 
<span id="Example 52-2"></span>
Line 254: Line 339:
 
  XMLBinder binder = context.createBinder();
 
  XMLBinder binder = context.createBinder();
 
  Employee emp = (Employee) binder.unmarshal(myDocument);
 
  Employee emp = (Employee) binder.unmarshal(myDocument);
 
  
 
In the preceding example, <tt>emp</tt> 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.
 
In the preceding example, <tt>emp</tt> 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 (<tt>Employee</tt>) and update the XML document using an instance of an <tt>XMLBinder</tt>.
+
The following example demonstrates how you can make changes to the object (<tt>Employee</tt>) and update the XML document using an instance of an <tt>XMLBinder</tt>.
 
+
  
 
<span id="''Example 52-3"></span>
 
<span id="''Example 52-3"></span>
Line 276: Line 359:
 
  </employee>
 
  </employee>
 
   
 
   
This example demonstrates how you can obtain an associated node for a subobject (<tt>Address</tt>) of the <tt>Employee</tt> using an instance of an <tt>XMLBinder</tt>.
+
The following example demonstrates how you can obtain an associated node for a subobject (<tt>Address</tt>) of the <tt>Employee</tt> using an instance of an <tt>XMLBinder</tt>.
  
 
<span id="Example 52-4"></span>
 
<span id="Example 52-4"></span>
Line 284: Line 367:
 
  Node addressNode = binder.getXMLNode(addr);
 
  Node addressNode = binder.getXMLNode(addr);
 
   
 
   
 
 
In the preceding example, the returned node (<tt>addressNode</tt>) is the XML node in the original XML document that was used to build this employee's <tt>Address</tt> object.
 
In the preceding example, the returned node (<tt>addressNode</tt>) is the XML node in the original XML document that was used to build this employee's <tt>Address</tt> object.
  
Line 294: Line 376:
 
  addressNode.setAttribute("apt-no", "1527");
 
  addressNode.setAttribute("apt-no", "1527");
 
  Address updatedAddressNode = binder.updateObject(addressNode);
 
  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.
 
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 <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.
+
=====How to Use JAXBContext=====
 +
<!-- 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.
  
 
The <tt>JAXBContext</tt> object is thread-safe.
 
The <tt>JAXBContext</tt> object is thread-safe.
Line 310: Line 392:
 
  PurchaseOrder purchaseOrder =  
 
  PurchaseOrder purchaseOrder =  
 
     (PurchaseOrder)unmarshaller.unmarshal(new File("purchaseOrder.xml"));
 
     (PurchaseOrder)unmarshaller.unmarshal(new File("purchaseOrder.xml"));
 +
-->
 +
You can create an instance of <tt>JAXBContext</tt> from a collection of classes that are to be bound to XML. This will generate a EclipseLink project from the classes dynamically at run time. 
 +
 +
Using the instance of <tt>JAXBContext</tt> you can obtain <tt>Marshaller</tt> and <tt>Unmarshaller</tt> instances to operate on those classes, as the [[#Example 52-6|Creating and Using JAXBContext]] example shows. Note that this example assumes that you configure your application classpath to include your domain object class files.
 +
 +
<span id="Example 52-6"></span>
 +
''''' Creating and Using JAXBContext'''''
 +
Class[] classes = {Employee.class, Address.class, Department.class};
 +
JAXBContext jaxbContext = JAXBContext.newInstance(classes);
 +
Marshaller marshaller = jaxbContext.createMarshaller();
 +
marshaller.marshal(myEmployee, myOutput);
 +
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' The <tt>JAXBContext</tt> object is thread-safe.
 +
|}
 +
 +
 +
=====How to Use JAXBElement=====
 +
EclipseLink lets you marshal to and unmarshal from <tt>JAXBElement</tt> types.  The <tt>javax.xml.bind.JAXBElement</tt> class provides access to the following basic properties of an XML element:
 +
* its qualified name, which is composed of <tt>{target namespace}</tt> and <tt>{name}</tt>
 +
* its value, which is an instance of the Java class binding of its <tt>{type definition}</tt>
 +
* whether or not the element's content is <tt>{nillable}</tt>
 +
 +
EclipseLink supports the following JAXB element marshal API defined in the <tt>Marshaller</tt>:
 +
* <tt>marshal(java.lang.Object jaxbElement, java.io.Writer writer)</tt>
 +
* <tt>marshal(java.lang.Object jaxbElement, java.io.OutputStream os)</tt>
 +
* <tt>marshal(java.lang.Object jaxbElement, org.xml.sax.ContentHandler)</tt>
 +
* <tt>marshal(java.lang.Object jaxbElement, javax.xml.transform.Result)</tt>
 +
* <tt>marshal(java.lang.Object jaxbElement, org.w3c.dom.Node)</tt>
 +
* <tt>marshal(java.lang.Object jaxbElement, javax.xml.stream.XMLStreamWriter writer)</tt>
 +
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note:''' If the first parameter is not a <tt>JAXBElement</tt> instance, the marshal operation will throw an <tt>org.eclipse.persistence.exceptions.XMLMarshalException.MARSHAL_EXCEPTION</tt>.
 +
|}
 +
 +
 +
EclipseLink provides implementation of the following JAXB element unmarshal API defined in the  <tt>Unarshaller</tt>:
 +
* <tt><T> JAXBElement<T> unmarshal(org.w3c.dom.Node node, Class<T> declaredType)</tt>
 +
* <tt><T> JAXBElement<T> unmarshal(javax.xml.transform.Source source, Class<T> declaredType)</tt>
 +
* <tt><T> JAXBElement<T> unmarshal(javax.xml.stream.XMLStreamReader streamReader, Class<T> declaredType)</tt>
 +
* <tt><T> JAXBElement<T> unmarshal(javax.xml.stream.XMLEventReader eventReader, Class<T> declaredType)</tt>
 +
 +
  
 
===JAXB Validation===
 
===JAXB Validation===
Line 325: Line 454:
 
If validation errors are encountered, EclipseLink stops validating the object tree and creates a <tt>ValidationEvent</tt> object, according to the JAXB specification. If an error occurs in a subobject, EclipseLink will not validate further down that object's subtree.
 
If validation errors are encountered, EclipseLink stops validating the object tree and creates a <tt>ValidationEvent</tt> 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|Using EclipseLink JAXB Compiler Generated Files at Run Time]].
+
For more information on using EclipseLink XML to perform validation, see [[#Using EclipseLink JAXB Compiler-Generated Files at Run Time|Using EclipseLink JAXB Compiler-Generated Files at Run Time]].
  
 
For additional information on JAXB and validation, refer to the JAXB specification at <tt>http://java.sun.com/xml/jaxb/</tt>.
 
For additional information on JAXB and validation, refer to the JAXB specification at <tt>http://java.sun.com/xml/jaxb/</tt>.
Line 336: Line 465:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Concept]]
 
[[Category: Concept]]
 
[[Category: XML]]
 
[[Category: XML]]

Latest revision as of 11:10, 23 July 2012

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


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.

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 defines annotations to control the mapping of Java objects to XML, but it also defines a default set of mappings. Using the defaults, EclipseLink can marshall a set of objects into XML, and unmarshall an XML documennt into objects. 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 an 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) the required JAXB files (see Working with JAXB-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.


Generating EclipseLink Project and XML Schema Using JAXB Annotations

The EclipseLink JAXB compiler generates a EclipseLink project and an XML schema using the following JAXB annotations:

  • XmlRootElement - Indicates that a class should be mapped to a root-level element in a schema.
    The element name and namespace are specified in this annotation.
    This is a class-level annotation.
  • XmlElement - Indicates that a particular attribute on a Java class should be mapped to an XML element in the schema.
    The name and namespace can be specified by this annotation.
    This is a field-level annotation.
  • XmlElementRef - Indicates that a particular attribute on a Java class should be mapped in the schema to an XML element derived from the attribute's type.
    The name and namespace can be specified by this annotation.
    This is a field-level annotation.
    For more information, see Substitution Groups.
  • XmlElementRefs - Contains a collection of XmlElementRef annotations.
    This is a field-level annotation.
    For more information, see Substitution Groups.
  • XmlAttribute - Indicates that the Java attribute should map to an XML attribute in the schema.
    Name and namespace should be provided.
    This is a field-level annotation.
  • XmlElementWrapper - Specifies a wrapper element around another element or attribute.
    You can use this annotation to create a grouping element around a collection.
    This is a field-level annotation.
  • XmlList - Indicates that a collection property should map to a space-separated list in XML.
    This is a field-level annotation.
  • XmlType - Defines the complex-type for a class.
    Using this annotation’s propOrder property, you can specify the order in which to map elements. The propOrder property also determines if the schema should contain a sequence or an all. Depending on the structure of the class, it will either map to a ComplexType, a SimpleType, or a ComplexType with SimpleContent.
    This is a class-level annotation.
  • XmlTransient - Indicates that a mapping should not be generated for a particular field.
    This is a marker annotation.
    This is a field-level annotation.
  • XmlSchema - Specifies the target namespace for a schema.
    You can also use this annotation to configure namespace prefix mappings with the XmlNs annotation.
    This is a package-level annotation.
  • XmlNs - Appears only in an XmlSchema annotation to specify namespace-prefix mappings.
    This is a package-level annotation.
  • XmlValue - Maps an attribute to a text node under the parent class (for example, an Xpath of "text( )").
    Also indicates that the owning class should map to either a SimpleType or a ComplexType with SimpleContent.
    This is a field-level annotation.
  • XmlEnum - Indicates that a JDK 1.5 Enum type should map to a simple type with enumeration facets in the schema.
    The base schema type is specified on this annotation.
    This is a field-level annotation.
  • XmlEnumValue - Lets you specify the enumeration facets to be used in the schema, if they are to be different from the string values of the Enum constants specified in Java.
    This is a field-level annotation.
  • XmlAccessorType - Specifies how the classes’ attributes should be processed.
    This is a package- or class-level annotation.
    The following are valid values:
    • FIELD – Process all the public and/or private fields of the class.
    • PROPERTY – Process all the public or private get and set method pairs on the class.
    • PUBLIC_MEMBER – Process all the public fields and public get and set method pairs on the class.
    • NONE – Only process members that are annotated with JAXB annotations.
  • XmlAccessorOrder - Specifies the order in which properties are to be processed.
    This is a package- or class-level annotation.
    The following are valid values:
    • DEFAULT
    • ALPHABETICAL.
  • XmlSchemaType - If specified at a property level, indicates the schema type that should be used in schema generation.
    If used as part of an XmlSchemaTypes annotation, overrides default schema types at a package level.
    This is a property- or a package-level annotation.
  • XmlSchemaTypes - Contains a collection of XmlSchemaType annotations. Each one specifies a Java class and a XML schema type pair that should be used as a default for this package.
    This is a package-level annotation.
  • XmlAnyAttribute - Specifies that a Map property should be mapped to an xs:any attribute in the schema. For more information, see XML Any Attribute Mapping.
    This is a filed-level annotation.

For more information, see Chapter 8 of JAXB Specification at http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html


Note: The EclipseLink project is generated from a collection of annotated Java classes with support for relationships, collection-style mappings, and JDK 1.5 enumerations.

The schema is generated from a set of annotated Java classes with support for relationships.


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.


Implementation Classes

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

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.



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 XMLContext

EclipseLink provides an org.eclipse.persistence.ox.XMLContext class with which you can create instances of EclipseLink XMLMarshaller, XMLUnmarshaller, XMLBinder (see How to Use EclipseLink XMLBinder), 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. Create the XMLContext using its constructor method and by passing in the session name defined in the sessions.xml file, as the following example shows:

XMLContext context = new XMLContext("mysession");

You can also create the XMLContext from multiple sessions using a colon separated list of session names, as the following example shows:

XMLContext context = new XMLContext("session1:session2:session3");

Use the XMLContext to create an EclipseLink XMLMarshaller, XMLUnmarshaller, XMLBinder, and XMLValidator, as follows:

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 Marshal and Unmarshal Events

You can provide EclipseLink XMLMarshaller and XMLUnmarshaller with additional functionality at run time by registering them with a listener to handle specific event callbacks. This allows for extra processing on a business object either immediately before, or immediately after an object is written to or read from XML.

There are two types of event callbacks that you can handle in two different ways:

  1. To handle listener-based callbacks, set an event handler on an instance of XMLMarshaller or XMLUnmarshaller that implements a required interface, such as XMLMarshalListener or XMLUnmarshalListener. The events are triggered on the marshaller or unmarshaller's listener for any classes being marshalled or unmarshalled.
  2. To handle class-specific callbacks, you need to provide the required callback methods on your business objects.


Note: If you specify both the listener and the business object callbacks, the class-specific method will be invoked before the listener event.


This example shows how to create your custom event listeners.

Implementing the EclipseLink XMLMarhsalListener and XMLUnmarhsalListener Interfaces

public class EmployeeMarshalListener implements XMLMarshalListener {

   public void beforeMarshal(Object target) {
       // do something
   }

   public void afterMarshal(Object target) {
       // do something
   }
)


public class EmployeeUnmarshalListener implements XMLUnmarshalListener {

   public void beforeUnmarshal(Object target, Object parent) {
       // do something
   }

   public void afterUnmarshal(Object target, Object parent) {
       // do something
   }
}

The following examples show how to use the listeners in your application.

Using the Marshal Listener

...
XMLMarshaller marshaller = context.createMarshaller();
marshaller.setMarshalListener(new EmployeeMarshalListener());
marshaller.marshal(myObject, System.out);
...

Using the Unmarshal Listener

...
XMLUnmarshaller unmarshaller = context.createUnmarshaller();
unmarshaller.setUnmarshalListener(new EmployeeUnmarshalListener());
Object myObject = unmarshaller.unmarshal(myFile); 
...


How to Use EclipseLink XMLBinder

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 (relative to other mapped content) in the node.

When unmarshalling a document that contains only unmapped content, setting some values and then marshalling, the XMLBinder adds new elements before existing unmapped data, such as comments and processing instructions.

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.

The following 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");
binder.updateXML(emp);

In the preceding example, the updateXML method will update the cached node in the binder. 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>

The following 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 JAXBContext

You can create an instance of JAXBContext from a collection of classes that are to be bound to XML. This will generate a EclipseLink project from the classes dynamically at run time.

Using the instance of JAXBContext you can obtain Marshaller and Unmarshaller instances to operate on those classes, as the Creating and Using JAXBContext example shows. Note that this example assumes that you configure your application classpath to include your domain object class files.

Creating and Using JAXBContext

Class[] classes = {Employee.class, Address.class, Department.class};
JAXBContext jaxbContext = JAXBContext.newInstance(classes);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.marshal(myEmployee, myOutput);


Note: The JAXBContext object is thread-safe.


How to Use JAXBElement

EclipseLink lets you marshal to and unmarshal from JAXBElement types. The javax.xml.bind.JAXBElement class provides access to the following basic properties of an XML element:

  • its qualified name, which is composed of {target namespace} and {name}
  • its value, which is an instance of the Java class binding of its {type definition}
  • whether or not the element's content is {nillable}

EclipseLink supports the following JAXB element marshal API defined in the Marshaller:

  • marshal(java.lang.Object jaxbElement, java.io.Writer writer)
  • marshal(java.lang.Object jaxbElement, java.io.OutputStream os)
  • marshal(java.lang.Object jaxbElement, org.xml.sax.ContentHandler)
  • marshal(java.lang.Object jaxbElement, javax.xml.transform.Result)
  • marshal(java.lang.Object jaxbElement, org.w3c.dom.Node)
  • marshal(java.lang.Object jaxbElement, javax.xml.stream.XMLStreamWriter writer)


Note: If the first parameter is not a JAXBElement instance, the marshal operation will throw an org.eclipse.persistence.exceptions.XMLMarshalException.MARSHAL_EXCEPTION.


EclipseLink provides implementation of the following JAXB element unmarshal API defined in the Unarshaller:

  • <T> JAXBElement<T> unmarshal(org.w3c.dom.Node node, Class<T> declaredType)
  • <T> JAXBElement<T> unmarshal(javax.xml.transform.Source source, Class<T> declaredType)
  • <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLStreamReader streamReader, Class<T> declaredType)
  • <T> JAXBElement<T> unmarshal(javax.xml.stream.XMLEventReader eventReader, Class<T> declaredType)


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