public abstract class NamespacePrefixMapper extends Object
| Constructor and Description |
|---|
NamespacePrefixMapper() |
| 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
getPreDeclaredNamespaceUris() but allows the
(prefix,nsUri) pairs to be returned. |
abstract String |
getPreferredPrefix(String namespaceUri,
String suggestion,
boolean requirePrefix)
Returns a preferred prefix for the given namespace URI.
|
public abstract String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix)
As noted in the return value portion of the javadoc, there are several cases where the preference cannot be honored. Specifically, as of JAXB RI 2.0 and onward:
String),
partly to simplify the marshaller.JAXBContext
includes classes that use the empty namespace URI. This allows the JAXB RI
to reserve the "" prefix for the empty namespace URI, which is the only
possible prefix for the URI. This restriction is also to simplify the
marshaller.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.public String[] getPreDeclaredNamespaceUris()
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>
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.
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.
For example, by returning new String[]{"urn:foo"}, the
marshaller will produce:
<?xml version="1.0"?> <root xmlns:ns1="urn:foo"> <ns1:child> ... </ns1:child> <ns1:child> ... </ns1:child> <ns1:child> ... </ns1:child> ... </root>
To control prefixes assigned to those namespace URIs, use the
getPreferredPrefix(String, String, boolean) method.
Strings. 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 "".public String[] getPreDeclaredNamespaceUris2()
getPreDeclaredNamespaceUris() but allows the
(prefix,nsUri) pairs to be returned.
With getPreDeclaredNamespaceUris(), applications who wish to
control the prefixes as well as the namespaces needed to implement both
getPreDeclaredNamespaceUris() and
getPreferredPrefix(String, String, boolean).
This version eliminates the needs by returning an array of pairs.
public String[] getContextualNamespaceDecls()
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>
Copyright © 2014–2015 Philip Helger. All rights reserved.