+ * 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: + * + *
+ * 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
+ * {@link #getPreferredPrefix(String, String, boolean)} method.
+ *
+ * @return
+ * A list of namespace URIs as an array of {@link String}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 "".
+ *
+ * @since
+ * JAXB RI 1.0.2
+ */
+ public String[] getPreDeclaredNamespaceUris() {
+ return EMPTY_STRING;
+ }
+
+ /**
+ * Similar to {@link #getPreDeclaredNamespaceUris()} but allows the
+ * (prefix,nsUri) pairs to be returned.
+ *
+ *
+ * With {@link #getPreDeclaredNamespaceUris()}, applications who wish to control + * the prefixes as well as the namespaces needed to implement both + * {@link #getPreDeclaredNamespaceUris()} and {@link #getPreferredPrefix(String, String, boolean)}. + * + *
+ * This version eliminates the needs by returning an array of pairs. + * + * @return + * 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. + * + * @since + * JAXB RI 2.0 beta + */ + public String[] getPreDeclaredNamespaceUris2() { + return EMPTY_STRING; + } + + /** + * 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.) + * + *
+ * 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 {@link XMLStreamWriter}, + * {@link XMLEventWriter}, {@link DOMResult}, or {@link 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 {@link 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: + *
+ * + * @return + * 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. + * + * @since JAXB RI 2.0 beta + */ + public String[] getContextualNamespaceDecls() { + return EMPTY_STRING; + } +}+ * <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> + *