org.docx4j.jaxb.generic

Class NamespacePrefixMapper

java.lang.Object

org.docx4j.jaxb.generic.NamespacePrefixMapper

All Implemented Interfaces:

McIgnorableNamespaceDeclarator, NamespacePrefixMapperInterface

public class NamespacePrefixMapper
extends Object
implements NamespacePrefixMapperInterface, McIgnorableNamespaceDeclarator

NamespacePrefixMapper, which could be used by MOXy (relying on org.eclipse.persistence.internal.oxm.record.namespaces.NamespacePrefixMapperWrapper) But instead (to avoid additional reflection), we use org.docx4j.jaxb.moxy.NamespacePrefixMapper So this class isn't currently used.

Author:

jharrop

Constructor Summary

Constructors

Constructor and Description
NamespacePrefixMapper()

Method Summary

Modifier and Type	Method and Description
String[]	getContextualNamespaceDecls() Returns a list of (prefix,namespace URI) pairs that represents namespace bindings available on ancestor elements (that need not be repeated by the JAXB RI.)
String[]	getPreDeclaredNamespaceUris() Returns a list of namespace URIs that should be declared at the root element.
String[]	getPreDeclaredNamespaceUris2() Similar to NamespacePrefixMapperInterface.getPreDeclaredNamespaceUris() but allows the (prefix,nsUri) pairs to be returned.
String	getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix) Returns a preferred prefix for the given namespace URI.
void	setMcIgnorable(String mcIgnorable)

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

setMcIgnorable

public void setMcIgnorable(String mcIgnorable)

Specified by:

setMcIgnorable in interface McIgnorableNamespaceDeclarator

getPreferredPrefix

public String getPreferredPrefix(String namespaceUri,
                                 String suggestion,
                                 boolean requirePrefix)

Returns a preferred prefix for the given namespace URI. This method is intended to be overrided by a derived class.

Specified by:

getPreferredPrefix in interface NamespacePrefixMapperInterface

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. Typically this value comes from 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 preferred 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.

getPreDeclaredNamespaceUris

public 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="../../../../org/docx4j/jaxb/generic/NamespacePrefixMapper.html#getPreferredPrefix-java.lang.String-java.lang.String-boolean-"><code>getPreferredPrefix(java.lang.String, java.lang.String, boolean)</code></a> method.</div>
<dl>
<dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
<dd><code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris--">getPreDeclaredNamespaceUris</a></code>&nbsp;in interface&nbsp;<code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html" title="interface in org.docx4j.jaxb">NamespacePrefixMapperInterface</a></code></dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>A list of namespace URIs as an array of <a href="http://download.oracle.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang"><code>String</code></a>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>.</dd>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>JAXB RI 1.0.2</dd>
</dl>
</li>
</ul>
<a name="getPreDeclaredNamespaceUris2--">
<!--   -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>getPreDeclaredNamespaceUris2</h4>
<pre>public&nbsp;<a href="http://download.oracle.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]&nbsp;getPreDeclaredNamespaceUris2()</pre>
<div class="block"><span class="descfrmTypeLabel">Description copied from interface:&nbsp;<code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris2--">NamespacePrefixMapperInterface</a></code></span></div>
<div class="block">Similar to <a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris--"><code>NamespacePrefixMapperInterface.getPreDeclaredNamespaceUris()</code></a> but allows the
 (prefix,nsUri) pairs to be returned.

 <p>
 With <a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris--"><code>NamespacePrefixMapperInterface.getPreDeclaredNamespaceUris()</code></a>, applications who wish to control
 the prefixes as well as the namespaces needed to implement both
 <a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris--"><code>NamespacePrefixMapperInterface.getPreDeclaredNamespaceUris()</code></a> and <a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreferredPrefix-java.lang.String-java.lang.String-boolean-"><code>NamespacePrefixMapperInterface.getPreferredPrefix(String, String, boolean)</code></a>.

 <p>
 This version eliminates the needs by returning an array of pairs.</div>
<dl>
<dt><span class="overrideSpecifyLabel">Specified by:</span></dt>
<dd><code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getPreDeclaredNamespaceUris2--">getPreDeclaredNamespaceUris2</a></code>&nbsp;in interface&nbsp;<code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html" title="interface in org.docx4j.jaxb">NamespacePrefixMapperInterface</a></code></dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>always return a non-null (but possibly empty) array. The array stores
      data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent
      the empty namespace URI and the default prefix. Null is not allowed as a value
      in the array.</dd>
</dl>
</li>
</ul>
<a name="getContextualNamespaceDecls--">
<!--   -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>getContextualNamespaceDecls</h4>
<pre>public&nbsp;<a href="http://download.oracle.com/javase/6/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]&nbsp;getContextualNamespaceDecls()</pre>
<div class="block"><span class="descfrmTypeLabel">Description copied from interface:&nbsp;<code><a href="../../../../org/docx4j/jaxb/NamespacePrefixMapperInterface.html#getContextualNamespaceDecls--">NamespacePrefixMapperInterface</a></code></span></div>
<div class="block">Returns a list of (prefix,namespace URI) pairs that represents
 namespace bindings available on ancestor elements (that need not be repeated
 by the JAXB RI.)

 <p>
 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.

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

 <p>
 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.

 <p>
 It is <b>NOT</b> 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:
 <pre><xmp>
   <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>
 

Specified by:

getContextualNamespaceDecls in interface NamespacePrefixMapperInterface

Returns:

always return a non-null (but possibly empty) array. The array stores data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent the empty namespace URI and the default prefix. Null is not allowed as a value in the array.