Java Doc for NamespacePrefixMapper.java in  » 6.0-JDK-Modules » jaxb-impl » com » sun » xml » bind » marshaller » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Sometimes JAXB is used to marshal an XML document, which will be used as a subtree of a bigger document.

By default, the JAXB RI 1.0.x produces namespace declarations only when they are necessary, only at where they are used.

With NamespacePrefixMapper.getPreDeclaredNamespaceUris() , applications who wish to control the prefixes as well as the namespaces needed to implement both NamespacePrefixMapper.getPreDeclaredNamespaceUris() and NamespacePrefixMapper.getPreferredPrefix(String,String,boolean) .

This version eliminates the needs by returning an array of pairs. always return a non-null (but possibly empty) array.

Sometimes JAXB is used to marshal an XML document, which will be used as a subtree of a bigger document. When this happens, it's nice for a JAXB marshaller to be able to use in-scope namespace bindings of the larger document and avoid declaring redundant namespace URIs.

This is automatically done when you are marshalling to XMLStreamWriter , XMLEventWriter , DOMResult , or Node , because those output format allows us to inspect what's currently available as in-scope namespace binding. However, with other output format, such as OutputStream , the JAXB RI cannot do this automatically. That's when this method comes into play.

Namespace bindings returned by this method will be used by the JAXB RI, but will not be re-declared. They are assumed to be available when you insert this subtree into a bigger document.

It is NOT OK to return the same binding, or give the receiver a conflicting binding information. It's a responsibility of the caller to make sure that this doesn't happen even if the ancestor elements look like:

 <foo:abc xmlns:foo="abc">
 <foo:abc xmlns:foo="def">
 <foo:abc xmlns:foo="abc">
 ... JAXB marshalling into here.
 </foo:abc>
 </foo:abc>
 </foo:abc>
 

By default, the JAXB RI 1.0.x produces namespace declarations only when they are necessary, only at where they are used. Because of this lack of look-ahead, sometimes the marshaller produces a lot of namespace declarations that look redundant to human eyes. For example,

 <?xml version="1.0"?>
 <root>
 <ns1:child xmlns:ns1="urn:foo"> ... </ns1:child>
 <ns2:child xmlns:ns2="urn:foo"> ... </ns2:child>
 <ns3:child xmlns:ns3="urn:foo"> ... </ns3:child>
 ...
 </root>
 <xmp></pre>
 <p>
 The JAXB RI 2.x mostly doesn't exhibit this behavior any more,
 as it declares all statically known namespace URIs (those URIs
 that are used as element/attribute names in JAXB annotations),
 but it may still declare additional namespaces in the middle of
 a document, for example when (i) a QName as an attribute/element value
 requires a new namespace URI, or (ii) DOM nodes as a portion of an object
 tree requires a new namespace URI.
 <p>
 If you know in advance that you are going to use a certain set of
 namespace URIs, you can override this method and have the marshaller
 declare those namespace URIs at the root element.
 <p>
 For example, by returning <code>new String[]{"urn:foo"}</code>,
 the marshaller will produce:
 <pre><xmp>
 <?xml version="1.0"?>
 <root xmlns:ns1="urn:foo">
 <ns1:child> ... </ns1:child>
 <ns1:child> ... </ns1:child>
 <ns1:child> ... </ns1:child>
 ...
 </root>
 <xmp></pre>
 <p>
 To control prefixes assigned to those namespace URIs, use the
<a href="NamespacePrefixMapper.java.java-doc.htm#getPreferredPrefixStringStringboolean"><B>NamespacePrefixMapper.getPreferredPrefix(String,String,boolean)</B></a>  method. 
A list of namespace URIs as an array of <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a>s.This method can return a length-zero array but not null.None of the array component can be null. To representthe empty namespace, use the empty string <code>""</code>.<BR><B>since:</B><BR>&nbsp;&nbsp; JAXB RI 1.0.2 </td></tr></table><BR><br> <hr width=800><a name="getPreDeclaredNamespaceUris2"></a><table border=0 width=800><tr><td colspan=2><font size=+1><B>getPreDeclaredNamespaceUris2</B></font></td></tr><tr><td colspan=2><font size=-1><font color=#7f0055><B>public</B></font>  <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a>[] getPreDeclaredNamespaceUris2()</font><A href="NamespacePrefixMapper.java.htm#getPreDeclaredNamespaceUris2">(Code)</a></td></tr><tr><td width=30></td><td> Similar to 
<a href="NamespacePrefixMapper.java.java-doc.htm#getPreDeclaredNamespaceUris"><B>NamespacePrefixMapper.getPreDeclaredNamespaceUris()</B></a>  but allows the
 (prefix,nsUri) pairs to be returned.
 <p>
 With 
<a href="NamespacePrefixMapper.java.java-doc.htm#getPreDeclaredNamespaceUris"><B>NamespacePrefixMapper.getPreDeclaredNamespaceUris()</B></a> , applications who wish to control
 the prefixes as well as the namespaces needed to implement both
<a href="NamespacePrefixMapper.java.java-doc.htm#getPreDeclaredNamespaceUris"><B>NamespacePrefixMapper.getPreDeclaredNamespaceUris()</B></a>  and 
<a href="NamespacePrefixMapper.java.java-doc.htm#getPreferredPrefixStringStringboolean"><B>NamespacePrefixMapper.getPreferredPrefix(String,String,boolean)</B></a> .
 <p>
 This version eliminates the needs by returning an array of pairs.
always return a non-null (but possibly empty) array. The array storesdata like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to representthe empty namespace URI and the default prefix. Null is not allowed as a valuein the array.<BR><B>since:</B><BR>&nbsp;&nbsp; JAXB RI 2.0 beta</td></tr></table><BR><br> <hr width=800><a name="getPreferredPrefixStringStringboolean"></a><table border=0 width=800><tr><td colspan=2><font size=+1><B>getPreferredPrefix</B></font></td></tr><tr><td colspan=2><font size=-1><font color=#7f0055><B>abstract</B></font> <font color=#7f0055><B>public</B></font>  <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a> getPreferredPrefix(<a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a> namespaceUri, <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a> suggestion, boolean requirePrefix)</font><A href="NamespacePrefixMapper.java.htm#getPreferredPrefixStringStringboolean">(Code)</a></td></tr><tr><td width=30></td><td> Returns a preferred prefix for the given namespace URI.
 This method is intended to be overrided by a derived class.
<BR><B>Parameters:</B><BR>&nbsp;&nbsp;namespaceUri - The namespace URI for which the prefix needs to be found.Never be null. "" is used to denote the default namespace.<BR><B>Parameters:</B><BR>&nbsp;&nbsp;suggestion - When the content tree has a suggestion for the prefixto the given namespaceUri, that suggestion is passed as aparameter. Typicall this value comes from the QName.getPrefixto show the preference of the content tree. This parametermay be null, and this parameter may represent an alreadyoccupied prefix. <BR><B>Parameters:</B><BR>&nbsp;&nbsp;requirePrefix - If this method is expected to return non-empty prefix.When this flag is true, it means that the given namespace URIcannot be set as the default namespace.null if there's no prefered prefix for the namespace URI.In this case, the system will generate a prefix for you.Otherwise the system will try to use the returned prefix,but generally there's no guarantee if the prefix will beactually used or not.return "" to map this namespace URI to the default namespace.Again, there's no guarantee that this preference will behonored.If this method returns "" when requirePrefix=true, the returnvalue will be ignored and the system will generate one.<BR><B>since:</B><BR>&nbsp;&nbsp;  JAXB 1.0.1</td></tr></table><BR><br> <hr width=800><table border=1 width=800><tr bgColor=#ccccff><td>Methods inherited from <B>java.lang.Object</B></td></tr><tr><td>native <font color=#7f0055><B>protected</B></font>  <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm"><B>Object</B></a> clone() throws <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/CloneNotSupportedException.java.htm"><B>CloneNotSupportedException</B></a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#clone">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#clone">(Java Doc)</a><br><font color=#7f0055><B>public</B></font>  boolean equals(<a href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm"><B>Object</B></a> obj)<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#equalsObject">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#equalsObject">(Java Doc)</a><br><font color=#7f0055><B>protected</B></font>  void finalize() throws <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/Throwable.java.htm"><B>Throwable</B></a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#finalize">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#finalize">(Java Doc)</a><br>final native <font color=#7f0055><B>public</B></font>  <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/Class.java.htm"><B>Class</B></a><?> getClass()<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#getClass">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#getClass">(Java Doc)</a><br>native <font color=#7f0055><B>public</B></font>  int hashCode()<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#hashCode">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#hashCode">(Java Doc)</a><br>final native <font color=#7f0055><B>public</B></font>  void notify()<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#notify">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#notify">(Java Doc)</a><br>final native <font color=#7f0055><B>public</B></font>  void notifyAll()<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#notifyAll">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#notifyAll">(Java Doc)</a><br><font color=#7f0055><B>public</B></font>  <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/String.java.htm"><B>String</B></a> toString()<A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#toString">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#toString">(Java Doc)</a><br>final native <font color=#7f0055><B>public</B></font>  void wait(long timeout) throws <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/InterruptedException.java.htm"><B>InterruptedException</B></a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#waitlong">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#waitlong">(Java Doc)</a><br>final <font color=#7f0055><B>public</B></font>  void wait(long timeout, int nanos) throws <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/InterruptedException.java.htm"><B>InterruptedException</B></a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#waitlongint">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#waitlongint">(Java Doc)</a><br>final <font color=#7f0055><B>public</B></font>  void wait() throws <a href="../../../../../../../6.0-JDK-Core/lang/java/lang/InterruptedException.java.htm"><B>InterruptedException</B></a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.htm#wait">(Code)</a><A href="../../../../../../../6.0-JDK-Core/lang/java/lang/Object.java.java-doc.htm#wait">(Java Doc)</a><br></td></tr></table><br></td></tr></table></td></tr></table><TABLE border=0><TR><TD height=10></TD></TR></TABLE>
<script type="text/javascript"><!--
google_ad_client="pub-1725451137117542";google_ad_width=728;google_ad_height=90;google_ad_format="728x90_as";google_ad_type="text_image";google_ad_channel="";google_color_border="ffffff";google_color_bg="ffffff";google_color_link="003399";google_color_text="000000";google_color_url="75a3ed";
//--></script><script type="text/javascript"src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script></td></tr></table></td></tr></table><center><TABLE border=0><TR align=left><TD><A href="/index.html">www.java2java.com</A> | <A href=../../../../../../../../../html/contact.htm>Contact Us</A></Td></TR><TR align=left><TD class=Templatetext>Copyright 2009 - 12 Demo Source and Support. All rights reserved.</TD></TR><TR align=left><TD>All other trademarks are property of their respective owners.</TD></TR></TABLE></center></BODY></HTML>