blob: 8d2360a6ca9ba2f20d22ba1c3084b6e61881658b [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>Customizing XML Name Conversions | 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:32Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Customizing XML Name Conversions" />
<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="advanced_concepts001.htm" title="Previous" type="text/html" />
<link rel="next" href="advanced_concepts003.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="advanced_concepts001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="advanced_concepts003.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="CHDCCCAF" name="CHDCCCAF"></a><a id="TLJAX365" name="TLJAX365"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Customizing XML Name Conversions</font></h1>
<p>JAXB has well-established rules for converting Java names to XML names, which can be overridden through the use of annotations. This can become burdensome if your names follow common rules (such as making everything upper-case). Starting with EclipseLink MOXy 2.3, you can override this default naming algorithm.</p>
<p>This example will create an implementation of <code>XMLNameTransformer</code> to provide a naming algorithm to MOXy.</p>
<a id="TLJAX366" name="TLJAX366"></a>
<div class="sect2"><a id="sthref139" name="sthref139"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Using the XMLNameTransformer</font></h2>
<p>The <code>XMLNameTransformer</code> interface defines several methods for customizing name generation:</p>
<ul>
<li>
<p><code>transformElementName</code> &ndash; called when creating an element from a Java field or method</p>
</li>
<li>
<p><code>transformAttributeName</code> &ndash; called when creating an attribute from a Java field or method</p>
</li>
<li>
<p><code>transformTypeName</code> &ndash; called when creating a simple type or complex type from a Java class</p>
</li>
<li>
<p><code>transformRootElementName</code> &ndash; called when creating a (root) simple type or complex type from a Java class</p>
</li>
</ul>
<p><a href="#CHDCIJJI">Example 8-2</a> defines an <code>XMLNameTransformer</code> that does the following:</p>
<ul>
<li>
<p>Root element will be the unqualified Java class name</p>
</li>
<li>
<p>Other types will be named (unqualified Java class name) + "Type"</p>
</li>
<li>
<p>Camel-case element names will be converted to lower-case, hyphenated names</p>
</li>
<li>
<p>XML attributes will appear in all upper-case</p>
</li>
</ul>
<div class="example"><a id="CHDCIJJI" name="CHDCIJJI"></a><a id="TLJAX367" name="TLJAX367"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 8-2 Using an XMLNameTransformer</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
package example;
public class NameGenerator implements org.eclipse.persistence.oxm.XMLNameTransformer {
// Use the unqualified class name as our root element name.
public String transformRootElementName(String name) {
return name.substring(name.lastIndexOf('.') + 1);
}
// The same algorithm as root element name plus "Type" appended to the end.
public String transformTypeName(String name) {
return transformRootElementName(name) + "Type";
}
// The name will be lower-case with word breaks represented by '-'.
// Note: A capital letter in the original name represents the start of a new word.
public String transformElementName(String name) {
StringBuilder strBldr = new StringBuilder();
for (char character : name.toCharArray()) {
if (Character.isUpperCase(character)) {
strBldr.append('-');
strBldr.append(Character.toLowerCase(character));
} else {
strBldr.append(character);
}
}
return strBldr.toString();
}
// The original name converted to upper-case.
public String transformAttributeName(String name) {
return name.toUpperCase();
}
}
</pre></div>
<!-- class="example" --></div>
<!-- class="sect2" -->
<a id="TLJAX368" name="TLJAX368"></a>
<div class="sect2"><a id="sthref140" name="sthref140"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Example Model</font></h2>
<p>The domain model in <a href="#CHDEEICC">Example 8-3</a> will be used. To save space, the accessors have been omitted.</p>
<div class="example"><a id="CHDEEICC" name="CHDEEICC"></a><a id="TLJAX369" name="TLJAX369"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 8-3 Customer</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
import javax.xml.bind.annotation.*;
@XmlRootElement
@XmlType(propOrder={"fullName", "shippingAddress"})
@XmlAccessorType(XmlAccessType.FIELD)
public class Customer {
@XmlAttribute
private long id;
private String fullName;
private Address shippingAddress;
}
</pre></div>
<!-- class="example" -->
<div class="example"><a id="TLJAX370" name="TLJAX370"></a><a id="sthref141" name="sthref141"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 8-4 Address.java</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
import javax.xml.bind.annotation.*;
@XmlAccessorType(XmlAccessType.FIELD)
public class Address {
@XmlAttribute
private String type;
private String street;
}
</pre></div>
<!-- class="example" --></div>
<!-- class="sect2" -->
<a id="TLJAX371" name="TLJAX371"></a>
<div class="sect2"><a id="sthref142" name="sthref142"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Specifying the Naming Algorithm</font></h2>
<p>Our implementation of the naming algorithm can be provided via the <code>@XmlNameTransformer</code> annotation (package or type level) or via the external bindings file in XML.</p>
<ol>
<li>
<p>At the type level:</p>
<pre xml:space="preserve" class="oac_no_warn">
@XmlNameTransformer(example.NameGenerator.class)
public class Customer
</pre></li>
<li>
<p>At the package level (package-info.java):</p>
<pre xml:space="preserve" class="oac_no_warn">
@XmlNameTransformer(example.NameGenerator.class)
package example;
</pre></li>
<li>
<p>External bindings file:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;xml-bindings xmlns='http://www.eclipse.org/eclipselink/xsds/persistence/oxm' xml-name-transformer='example.NameGenerator'&gt;
&lt;xml-schema/&gt;
&lt;java-types/&gt;
&lt;/xml-bindings&gt;
</pre></li>
</ol>
</div>
<!-- class="sect2" -->
<a id="TLJAX372" name="TLJAX372"></a>
<div class="sect2"><a id="sthref143" name="sthref143"></a>
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">XML Output</font></h2>
<p>Without any customization, JAXB's default naming algorithm will produce XML that looks like the following:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;customer id="123"&gt;
&lt;fullName&gt;Jane Doe&lt;/fullName&gt;
&lt;shippingAddress type="residential"&gt;
&lt;street&gt;1 Any Street&lt;/street&gt;
&lt;/shippingAddress&gt;
&lt;/customer&gt;
</pre>
<p>By leveraging our customized naming algorithm we can get the following output without specifying any additional metadata on our domain classes:</p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;Customer ID="123"&gt;
&lt;full-name&gt;Jane Doe&lt;/full-name&gt;
&lt;shipping-address TYPE="residential"&gt;
&lt;street&gt;1 Any Street&lt;/street&gt;
&lt;/shipping-address&gt;
&lt;/Customer&gt;
</pre></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="advanced_concepts001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="advanced_concepts003.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>