blob: 78a177038d8bef87a48610459918ca413293c4e6 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Using XML Bindings | EclipseLink 2.7 EclipseLink MOXy</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:25:31Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Using XML Bindings" />
<meta name="relnum" content="Release 2.7" />
<meta name="partnum" content="" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="runtime002.htm" title="Previous" type="text/html" />
<link rel="next" href="runtime004.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:1hjujor5_fg', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><div class="booktitle">Developing JAXB Applications Using EclipseLink MOXy,
<b>Release 2.7</b><br /></font></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_moxy.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="runtime002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="runtime004.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CACHCHAE" name="CACHCHAE"></a><a id="TLJAX136" name="TLJAX136"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Using XML Bindings</font></h1>
<p>In addition to standard JAXB annotations, EclipseLink offers another way of expressing your metadata: the EclipseLink XML Bindings document. Not only can XML Bindings separate your mapping information from your actual Java class, it can also be used for more advanced metadata tasks such as:</p>
<ul>
<li>
<p>Augmenting or overriding existing annotations with additional mapping information</p>
</li>
<li>
<p>Specifying all mappings information externally, with no annotations in Java at all</p>
</li>
<li>
<p>Defining your mappings across multiple Bindings documentsSpecifying "virtual" mappings that do not correspond to concrete Java fieldsand more..</p>
</li>
</ul>
<p>This section describes the XML Bindings format and demonstrates some basic use cases.</p>
<a id="TLJAX137" name="TLJAX137"></a>
<div class="sect2"><a id="sthref17" name="sthref17"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Understanding the XML Bindings Format</font></h2>
<p>An XML Bindings document is XML that specifies Java type information, mapping information, context-wide properties &ndash; everything you need to define your JAXB system. An example Bindings document is shown in <a href="#CACDBJHE">Example 2-9</a>.</p>
<div class="example"><a id="CACDBJHE" name="CACDBJHE"></a><a id="TLJAX138" name="TLJAX138"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-9 Sample Bindings Document</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="US-ASCII"?&gt;
&lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"
package-name="example" xml-accessor-type="PUBLIC_MEMBER" xml-accessor-order="ALPHABETICAL"
xml-mapping-metadata-complete="false" xml-name-transformer="example.NameGenerator"
supported-versions="2.4" &gt;
&lt;xml-schema element-form-default="QUALIFIED"&gt;
&lt;xml-ns prefix="ns1" namespace-uri="http://www.example.org/type" /&gt;
&lt;/xml-schema&gt;
&lt;java-types&gt;
&lt;java-type name="Employee"&gt;
&lt;xml-type namespace="http://www.example.org/type" /&gt;
&lt;java-attributes&gt;
&lt;xml-attribute java-attribute="empId" xml-path="@id" /&gt;
&lt;xml-element java-attribute="empName" name="name" /&gt;
&lt;xml-element java-attribute="salary" /&gt;
&lt;xml-element java-attribute="type" type="EmployeeType" /&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;java-type name="Company"&gt;
&lt;xml-root-element name="company" /&gt;
&lt;xml-attribute java-attribute="empId" xml-path="@id" /&gt;
&lt;xml-element java-attribute="empName" name="name" /&gt;
&lt;java-attributes&gt;
&lt;xml-element java-attribute="employees" name="employee"
type="example.Employee" container-type="java.util.ArrayList" /&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;/java-types&gt;
&lt;xml-registries&gt;
&lt;xml-registry name="example.ObjectFactory"&gt;
&lt;xml-element-decl java-method="createEmpleado"
name="empleado" type="example.Employee" /&gt;
&lt;xml-element-decl java-method="createCorporacion"
name="corporacion" type="example.Company" /&gt;
&lt;/xml-registry&gt;
&lt;/xml-registries&gt;
&lt;xml-enums&gt;
&lt;xml-enum java-enum="EmployeeType" value="java.lang.String"&gt;
&lt;xml-enum-value java-enum-value="CONTRACT"&gt;CONTRACT&lt;/xml-enum-value&gt;
&lt;xml-enum-value java-enum-value="PART_TIME"&gt;PART_TIME&lt;/xml-enum-value&gt;
&lt;xml-enum-value java-enum-value="FULL_TIME"&gt;FULL_TIME&lt;/xml-enum-value&gt;
&lt;/xml-enum&gt;
&lt;/xml-enums&gt;
&lt;/xml-bindings&gt;
</pre></div>
<!-- class="example" -->
<div class="tblhruleformal"><a id="TLJAX139" name="TLJAX139"></a><a id="sthref18" name="sthref18"></a><a id="sthref19" name="sthref19"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Table 2-1 Binding Document Attributes</font></em></strong></p>
<table class="HRuleFormal" title="Binding Document Attributes" summary="This table describes the binding document attributes." dir="ltr" border="1" width="100%" frame="hsides" rules="rows" cellpadding="3" cellspacing="0">
<col width="25%" />
<col width="*" />
<thead>
<tr align="left" valign="top">
<th align="left" valign="bottom" id="r1c1-t2"><font face="Arial, Helvetica, sans-serif"><strong>Attribute</strong></font></th>
<th align="left" valign="bottom" id="r1c2-t2"><font face="Arial, Helvetica, sans-serif"><strong>Description</strong></font></th>
</tr>
</thead>
<tbody>
<tr align="left" valign="top">
<td align="left" id="r2c1-t2" headers="r1c1-t2">
<p><code>&lt;xml-bindings&gt;</code></p>
</td>
<td align="left" headers="r2c1-t2 r1c2-t2">
<p>The root of the XML Bindings document. This is also where you can define top-level properties for your JAXB system, such as the <code>package-name</code> of your classes, specify a default <code>xml-accessor-type</code>, and so on.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r3c1-t2" headers="r1c1-t2">
<p><code>&lt;xml-schema&gt;</code></p>
</td>
<td align="left" headers="r3c1-t2 r1c2-t2">
<p>Defines properties related to the schema-level of your JAXB system. Corresponds to the JAXB <code>@XmlSchema</code> annotation.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r4c1-t2" headers="r1c1-t2">
<p><code>&lt;java-types&gt;</code></p>
</td>
<td align="left" headers="r4c1-t2 r1c2-t2">
<p>Defines mapping information for each of your Java classes.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r5c1-t2" headers="r1c1-t2">
<p><code>&lt;xml-enums&gt;</code></p>
</td>
<td align="left" headers="r5c1-t2 r1c2-t2">
<p>Defines Java enumerations that can be used with your Java types.</p>
</td>
</tr>
<tr align="left" valign="top">
<td align="left" id="r6c1-t2" headers="r1c1-t2">
<p><code>&lt;xml-registries&gt;</code></p>
</td>
<td align="left" headers="r6c1-t2 r1c2-t2">
<p>Defines an <code>ObjectFactory</code> for use in your JAXB system.</p>
</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="tblhruleformal" --></div>
<!-- class="sect2" -->
<a id="TLJAX140" name="TLJAX140"></a>
<div class="sect2"><a id="sthref20" name="sthref20"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Bootstrapping with XML Bindings</font></h2>
<p>When instantiating a <code>JAXBContext</code>, links to Bindings documents are passed in via the properties parameter, using a special key, <code>JAXBContextProperties.OXM_METADATA_SOURCE</code>. The value of this key will be a handle to the Bindings document, in the form of one of the following:</p>
<ul>
<li>
<p><code>java.io.File</code></p>
</li>
<li>
<p><code>java.io.InputStream</code></p>
</li>
<li>
<p><code>java.io.Reader</code></p>
</li>
<li>
<p><code>java.net.URL</code></p>
</li>
<li>
<p><code>javax.xml.stream.XMLEventReader</code></p>
</li>
<li>
<p><code>javax.xml.stream.XMLStreamReader</code></p>
</li>
<li>
<p><code>javax.xml.transform.Source</code></p>
</li>
<li>
<p><code>org.w3c.dom.Node</code></p>
</li>
<li>
<p><code>org.xml.sax.InputSource</code></p>
</li>
</ul>
<p>To bootstrap from multiple XML Bindings documents:</p>
<ul>
<li>
<p>Maps of the above inputs are supported, keyed on Java package name.</p>
</li>
<li>
<p>Lists of the above inputs are acceptable as well (<code>&lt;xml-bindings&gt;</code> must have package attribute).</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="TLJAX141" name="TLJAX141"></a>
<div class="sect2"><a id="sthref21" name="sthref21"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using XML Bindings with Annotations</font></h2>
<p>The most typical use of an XML Bindings document is in conjunction with JAXB annotations. You may have situation where you are not permitted to edit your Java domain classes, but want to add additional mapping functionality. Or, you may wish to avoid importing any EclipseLink code into your domain model, but still take advantage of MOXy's advanced mapping features. When Bindings metadata is provided during context creation, its mapping information will be combined with any JAXB annotation information.</p>
<p>For example, consider the simple JAXB domain class and its default JAXB XML representation shown in <a href="#CACJAIBJ">Example 2-10</a>.</p>
<div class="example"><a id="CACJAIBJ" name="CACJAIBJ"></a><a id="TLJAX142" name="TLJAX142"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-10 Sample JAXB Domain Class and XML</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
package example;
import javax.xml.bind.annotation.*;
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
@XmlAttribute
private Integer custId;
private String name;
private Double salary;
private byte[] picture;
...
}
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;customer custId="15"&gt;
&lt;name&gt;Bob Dobbs&lt;/name&gt;
&lt;salary&gt;51727.61&lt;/salary&gt;
&lt;picture&gt;AgQIECBA&lt;/picture&gt;
&lt;/customer&gt;
</pre></div>
<!-- class="example" -->
<p>Now, assume that we would like to make the following mapping changes:</p>
<ul>
<li>
<p>Change the XML element name of <code>custId</code> to <code>customer-id</code></p>
</li>
<li>
<p>Change the root element name of the class to <code>customer-info</code></p>
</li>
<li>
<p>Write the picture to XML as <code>picture-hex</code> in hex <code>binary</code> format, and use our own custom converter, <code>MyHexConverter</code>.</p>
</li>
</ul>
<p>We can specify these three customizations in an XML Bindings document as shown in <a href="#CACEDHHB">Example 2-11</a>.</p>
<div class="example"><a id="CACEDHHB" name="CACEDHHB"></a><a id="TLJAX143" name="TLJAX143"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-11 Customized XML Bindings</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="US-ASCII"?&gt;
&lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
package-name="example"&gt;
&lt;java-types&gt;
&lt;java-type name="Customer"&gt;
&lt;xml-root-element name="customer-info" /&gt;
&lt;java-attributes&gt;
&lt;xml-attribute java-attribute="custId" name="customer-id" /&gt;
&lt;xml-element java-attribute="picture" name="picture-hex"&gt;
&lt;xml-schema-type name="hexBinary" /&gt;
&lt;xml-java-type-adapter
value="example.adapters.MyHexConverter" /&gt;
&lt;/xml-element&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;/java-types&gt;
&lt;/xml-bindings&gt;
</pre></div>
<!-- class="example" -->
<p>The Bindings must then be provided during JAXB context creation. Bindings information is passed in via the <code>properties</code> argument:</p>
<div class="example"><a id="TLJAX144" name="TLJAX144"></a><a id="sthref22" name="sthref22"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-12 Providing Bindings</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
InputStream iStream = classLoader.getResourceAsStream("metadata/xml-bindings.xml");
Map&lt;String, Object&gt; <strong>properties</strong> = new HashMap&lt;String, Object&gt;();
properties.put(JAXBContextProperties.OXM_METADATA_SOURCE, iStream);
JAXBContext ctx = JAXBContext.newInstance(new Class[] { Customer.class }, properties);
</pre></div>
<!-- class="example" -->
<p>When providing Bindings, during JAXB context creation EclipseLink will:</p>
<ol>
<li>
<p><code>Customer.class</code> will be analyzed and JAXB mappings will be generated as usual.</p>
</li>
<li>
<p>The Bindings document is then analyzed, and the original JAXB mappings will be merged with the information in the Bindings document.</p>
</li>
</ol>
<p>After applying the XML Bindings, we have the desired XML representation:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;customer-info customer-id="15"&gt;
&lt;name&gt;Bob Dobbs&lt;/name&gt;
&lt;salary&gt;51727.61&lt;/salary&gt;
&lt;picture-hex&gt;020408102040&lt;/picture-hex&gt;
&lt;/customer-info&gt;
</pre></div>
<!-- class="sect2" -->
<a id="TLJAX145" name="TLJAX145"></a>
<div class="sect2"><a id="sthref23" name="sthref23"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using Multiple Bindings Documents</font></h2>
<p>Starting with version 2.3, EclipseLink allows you to use mapping information from multiple XML Bindings documents. Using this approach, you can split your metadata up as you wish.</p>
<div class="example"><a id="TLJAX146" name="TLJAX146"></a><a id="sthref24" name="sthref24"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-13 Using a List of XML Bindings:</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
...
FileReader file1 = new FileReader("base-bindings.xml");
FileReader file2 = new FileReader("override-bindings.xml");
List&lt;Object&gt; fileList = new ArrayList&lt;Object&gt;();
fileList.add(file1);
fileList.add(file2);
Map&lt;String, Object&gt; properties = new HashMap&lt;String, Object&gt;();
properties.put(JAXBContextProperties.OXM_METADATA_SOURCE, fileList);
JAXBContext ctx = JAXBContext.newInstance(new Class[] { Customer.class }, properties);
...
</pre></div>
<!-- class="example" -->
<p>When using a List of Bindings documents, each one must define the package attribute of <code>&lt;xml-bindings&gt;</code>, to indicate the package for each set of Bindings.</p>
<div class="example"><a id="TLJAX147" name="TLJAX147"></a><a id="sthref25" name="sthref25"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-14 Using a Map for multiple packages:</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
...
FileReader fooFile1 = new FileReader("foo/base-bindings.xml");
FileReader fooFile2 = new FileReader("foo/override-bindings.xml");
List&lt;Object&gt; fooFileList = new ArrayList&lt;Object&gt;();
fooFileList.add(fooFile1);
fooFileList.add(fooFile2);
FileReader barFile1 = new FileReader("bar/base-bindings.xml");
FileReader barFile2 = new FileReader("bar/override-bindings.xml");
List&lt;Object&gt; barFileList = new ArrayList&lt;Object&gt;();
barFileList.add(barFile1);
barFileList.add(barFile2);
Map&lt;String, List&gt; metadataMap = new HashMap&lt;String, List&gt;();
metadataMap.put("foo", fooFileList);
metadataMap.put("bar", barFileList);
properties.put(JAXBContextProperties.OXM_METADATA_SOURCE, metadataMap);
JAXBContext ctx = JAXBContext.newInstance(new Class[] { Customer.class }, properties);
...
</pre></div>
<!-- class="example" --></div>
<!-- class="sect2" -->
<a id="TLJAX148" name="TLJAX148"></a>
<div class="sect2"><a id="sthref26" name="sthref26"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Understanding Override Rules</font></h2>
<p>When multiple sources of metadata are encountered for the same package, a unified set of mappings will be created by merging the complete set of metadata. First, the annotations from the Java class will be processed, and then any XML Bindings information will be applied. The order that Bindings are specified is relevant; values in subsequent documents will override the ones defined in previous ones.</p>
<p>The following rules will be used for merging:</p>
<ul>
<li>
<p><code>xml-schema</code></p>
<ul>
<li>
<p>For values such as <code>namespace</code>, <code>elementform</code>, <code>attributeform</code>, the later file will override.</p>
</li>
<li>
<p>The list of namespace declarations from <code>XmlNs</code> will be merged into a single list containing all entries from all files.</p>
<p>In the case of conflicting entries (the same prefix bound to multiple namespaces), the last file will override the declarations from previous files.</p>
</li>
</ul>
</li>
<li>
<p><code>java-types</code></p>
<ul>
<li>
<p>The merged bindings will contain all unique <code>java-type</code> entries from all bindings files.</p>
</li>
<li>
<p>If the same <code>java-type</code> occurs in multiple files, any values that are set in the later file will override values from the previous file.</p>
</li>
<li>
<p>Properties on each <code>java-type</code> will be merged into a unified list. If the same property is referenced in multiple files, this will be an exception case.</p>
</li>
<li>
<p>Class-level <code>XmlJavaTypeAdpater</code> entries will be overridden if specified in a later bindings file.</p>
</li>
<li>
<p>Class-level <code>XmlSchemaTypes</code> will create a merged list. If an entry for the same type is listed in multiple bindings files at this level, the last file's entry will override all previous ones.</p>
</li>
</ul>
</li>
<li>
<p><code>xml-enums</code></p>
<ul>
<li>
<p>The merged bindings will contain all unique <code>xml-enum</code> entries from all bindings files.</p>
</li>
<li>
<p>For any duplicated java-enums, a merged list of <code>XmlEnumValues</code> will be created. If an entry for the same enum facet occurs in multiple files, the last file will override the value for that facet.</p>
</li>
</ul>
</li>
<li>
<p><code>xml-java-type-adapters</code></p>
<ul>
<li>
<p>Package-level Java type adapters will be merged into a single list. In the case that an adapter is specified for the same class in multiple files, the last file's entry will win.</p>
</li>
</ul>
</li>
<li>
<p><code>xml-registries</code></p>
<ul>
<li>
<p>Each unique <code>XmlRegistry</code> entry will be added to the final merged list of <code>XmlRegistries</code>.</p>
</li>
<li>
<p>For any duplicated <code>XmlRegistry</code> entries, a merged list of <code>XmlElementDecls</code> will be created.</p>
<p>In the case that an <code>XmlElementDecl</code> for the same <code>XmlRegistry</code> class appears in multiple bindings files, that <code>XmlElementDecl</code> will be replaced with the one from the later bindings.</p>
</li>
</ul>
</li>
<li>
<p><code>xml-schema-types</code></p>
<ul>
<li>
<p><code>XmlSchemaType</code> entries will be merged into a unified list.</p>
</li>
<li>
<p>In the case that an <code>XmlSchemaType</code> entry for the same java-type appears at the package level in multiple bindings files, the merged bindings will only contain the entry for the last one specified.</p>
</li>
</ul>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="TLJAX149" name="TLJAX149"></a>
<div class="sect2"><a id="sthref27" name="sthref27"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using Complete Metadata</font></h2>
<p>If you would like to store all of your metadata in XML Bindings and ignore any JAXB annotations in your Java class, you can include the <code>xml-mapping-metadata-complete</code> attribute in the <code>&lt;xml-bindings&gt;</code> element of your Bindings document. Default JAXB mappings will still be generated (the same as if you were using a completely un-annotated class with JAXB), and then any mapping data defined in the XML Bindings will be applied.</p>
<p>This could be used, for example, to map the same Java class to two completely different XML representations: the annotations on the actual Java class would define the first XML representation, and then a second XML representation could be defined in an XML Bindings document with <code>xml-mapping-metadata-complete="true"</code>. This would essentially give you a "blank canvas" to remap your Java class.</p>
<p>If you would like to ignore the default mappings that JAXB generates, you can specify <code>xml-accessor-type="NONE"</code> in your <code>&lt;java-type&gt;</code> element. Using this approach, only mappings that are explicitly defined in Bindings document will be applied.</p>
<p>Using the <strong>Customer</strong> example from above, the following examples demonstrate the XML representations that will be generated when using <code>xml-mapping-metadata-complet</code>e:</p>
<div class="example"><a id="TLJAX150" name="TLJAX150"></a><a id="sthref28" name="sthref28"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-15 Sample Customer Class</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
package example;
import javax.xml.bind.annotation.*;
@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
@XmlAttribute
private Integer custId;
private String name;
private Double salary;
private byte[] picture;
...
}
</pre></div>
<!-- class="example" -->
<div class="example"><a id="TLJAX151" name="TLJAX151"></a><a id="sthref29" name="sthref29"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-16 XML Bindings</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="US-ASCII"?&gt;
&lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
package-name="example" <strong>xml-mapping-metadata-complete="true"</strong>&gt;
&lt;java-types&gt;
&lt;java-type name="Customer"&gt;
&lt;xml-root-element /&gt;
&lt;java-attributes&gt;
&lt;xml-attribute java-attribute="name" name="customer-name" /&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;/java-types&gt;
&lt;/xml-bindings&gt;
</pre></div>
<!-- class="example" -->
<div class="example"><a id="TLJAX152" name="TLJAX152"></a><a id="sthref30" name="sthref30"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-17 XML Representation</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;customer&gt;
&lt;custId&gt;15&lt;/custId&gt;
&lt;customer-name&gt;Bob Dobbs&lt;/customer-name&gt;
&lt;picture&gt;AgQIECBA&lt;/picture&gt;
&lt;salary&gt;51727.61&lt;/salary&gt;
&lt;/customer&gt;
</pre></div>
<!-- class="example" -->
<ul>
<li>
<p>Default JAXB mapping is generated for <code>custId</code> (note that <code>custId</code> is now an XML element, as if there were no annotation on the Java field)</p>
</li>
<li>
<p>The name element has been renamed to <code>customer-name</code></p>
</li>
<li>
<p>Default JAXB mappings are generated for <code>picture</code> and <code>salary</code></p>
</li>
</ul>
<div class="example"><a id="TLJAX153" name="TLJAX153"></a><a id="sthref31" name="sthref31"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-18 XML Bindings (with xml-accessor-type="NONE")</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="US-ASCII"?&gt;
&lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
package-name="example" xml-mapping-metadata-complete="true"&gt;
&lt;java-types&gt;
&lt;java-type name="Customer" xml-accessor-type="NONE"&gt;
&lt;xml-root-element /&gt;
&lt;java-attributes&gt;
&lt;xml-attribute java-attribute="name" name="customer-name" /&gt;
&lt;/java-attributes&gt;
&lt;/java-type&gt;
&lt;/java-types&gt;
&lt;/xml-bindings&gt;
</pre></div>
<!-- class="example" -->
<div class="example"><a id="TLJAX154" name="TLJAX154"></a><a id="sthref32" name="sthref32"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 2-19 XML Representation</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;customer&gt;
&lt;customer-name&gt;Bob Dobbs&lt;/customer-name&gt;
&lt;/customer&gt;
</pre></div>
<!-- class="example" -->
<ul>
<li>
<p>Specifying <code>xml-accessor-type="NONE"</code> will prevent any default mappings from being generated</p>
</li>
<li>
<p>The XML representation contains only the mappings defined in the XML Bindings document</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="TLJAX155" name="TLJAX155"></a>
<div class="sect2"><a id="sthref33" name="sthref33"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using Virtual Mappings</font></h2>
<p>XML Bindings can also be used to specify virtual mappings &ndash; mappings that do not correspond to a concrete Java field. For example, you might want to use a <code>HashMap</code> as the underlying structure to hold data for certain mappings. For information on using Virtual Mappings, see <a href="advanced_concepts003.htm#CHDJHCCE">"Using Virtual Access Methods"</a>.</p>
</div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="runtime002.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="runtime004.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_moxy.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2013 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>