com.sun.xml.bind.marshaller
Class NamespacePrefixMapper

java.lang.Object
  extended by com.sun.xml.bind.marshaller.NamespacePrefixMapper

public abstract class NamespacePrefixMapper
extends java.lang.Object

Implemented by the user application to determine URI -> prefix mapping. This is considered as an interface, though it's implemented as an abstract class to make it easy to add new methods in a future.


Constructor Summary
NamespacePrefixMapper()
           
 
Method Summary
 java.lang.String[] getPreDeclaredNamespaceUris()
          Returns a list of namespace URIs that should be declared at the root element.
abstract  java.lang.String getPreferredPrefix(java.lang.String namespaceUri, java.lang.String suggestion, boolean requirePrefix)
          Returns a preferred prefix for the given namespace URI.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NamespacePrefixMapper

public NamespacePrefixMapper()
Method Detail

getPreferredPrefix

public abstract java.lang.String getPreferredPrefix(java.lang.String namespaceUri,
                                                    java.lang.String suggestion,
                                                    boolean requirePrefix)
Returns a preferred prefix for the given namespace URI. This method is intended to be overrided by a derived class.

Parameters:
namespaceUri - The namespace URI for which the prefix needs to be found. Never be null. "" is used to denote the default namespace.
suggestion - When the content tree has a suggestion for the prefix to the given namespaceUri, that suggestion is passed as a parameter. Typicall this value comes from the QName.getPrefix to show the preference of the content tree. This parameter may be null, and this parameter may represent an already occupied prefix.
requirePrefix - If this method is expected to return non-empty prefix. When this flag is true, it means that the given namespace URI cannot be set as the default namespace.
Returns:
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 be actually used or not. return "" to map this namespace URI to the default namespace. Again, there's no guarantee that this preference will be honored. If this method returns "" when requirePrefix=true, the return value will be ignored and the system will generate one.
Since:
JAXB 1.0.1

getPreDeclaredNamespaceUris

public java.lang.String[] getPreDeclaredNamespaceUris()
Returns a list of namespace URIs that should be declared at the root element.

By default, the JAXB RI 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>
 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="../../../../../com/sun/xml/bind/marshaller/NamespacePrefixMapper.html#getPreferredPrefix(java.lang.String, java.lang.String, boolean)"><CODE>getPreferredPrefix(String, String, boolean)</CODE></A> method.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>A list of namespace URIs as an array of <CODE>String</CODE>s.
      This method can return a length-zero array but not null.
      None of the array component can be null. To represent
      the empty namespace, use the empty string <code>""</code>.<DT><B>Since:</B></DT>
  <DD>JAXB RI 1.0.2</DD>
</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/NamespacePrefixMapper.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../com/sun/xml/bind/marshaller/MS1252Encoder.html" title="class in com.sun.xml.bind.marshaller"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../../../com/sun/xml/bind/marshaller/NamespaceSupport.html" title="class in com.sun.xml.bind.marshaller"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../../index.html?com/sun/xml/bind/marshaller/NamespacePrefixMapper.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="NamespacePrefixMapper.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>


</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>

</BODY>
</HTML>