aoqi@0: * As noted in the return value portion of the javadoc, there aoqi@0: * are several cases where the preference cannot be honored. aoqi@0: * Specifically, as of JAXB RI 2.0 and onward: aoqi@0: * aoqi@0: *
aoqi@0: * By default, the JAXB RI 1.0.x produces namespace declarations only when aoqi@0: * they are necessary, only at where they are used. Because of this aoqi@0: * lack of look-ahead, sometimes the marshaller produces a lot of aoqi@0: * namespace declarations that look redundant to human eyes. For example, aoqi@0: *
aoqi@0: * aoqi@0: *aoqi@0: * <?xml version="1.0"?> aoqi@0: * <root> aoqi@0: * <ns1:child xmlns:ns1="urn:foo"> ... </ns1:child> aoqi@0: * <ns2:child xmlns:ns2="urn:foo"> ... </ns2:child> aoqi@0: * <ns3:child xmlns:ns3="urn:foo"> ... </ns3:child> aoqi@0: * ... aoqi@0: * </root> aoqi@0: *
aoqi@0: * The JAXB RI 2.x mostly doesn't exhibit this behavior any more, aoqi@0: * as it declares all statically known namespace URIs (those URIs aoqi@0: * that are used as element/attribute names in JAXB annotations), aoqi@0: * but it may still declare additional namespaces in the middle of aoqi@0: * a document, for example when (i) a QName as an attribute/element value aoqi@0: * requires a new namespace URI, or (ii) DOM nodes as a portion of an object aoqi@0: * tree requires a new namespace URI. aoqi@0: * aoqi@0: *
aoqi@0: * If you know in advance that you are going to use a certain set of aoqi@0: * namespace URIs, you can override this method and have the marshaller aoqi@0: * declare those namespace URIs at the root element. aoqi@0: * aoqi@0: *
aoqi@0: * For example, by returning new String[]{"urn:foo"},
aoqi@0: * the marshaller will produce:
aoqi@0: *
aoqi@0: *aoqi@0: * <?xml version="1.0"?> aoqi@0: * <root xmlns:ns1="urn:foo"> aoqi@0: * <ns1:child> ... </ns1:child> aoqi@0: * <ns1:child> ... </ns1:child> aoqi@0: * <ns1:child> ... </ns1:child> aoqi@0: * ... aoqi@0: * </root> aoqi@0: *
aoqi@0: * To control prefixes assigned to those namespace URIs, use the
aoqi@0: * {@link #getPreferredPrefix(String, String, boolean)} method.
aoqi@0: *
aoqi@0: * @return
aoqi@0: * A list of namespace URIs as an array of {@link String}s.
aoqi@0: * This method can return a length-zero array but not null.
aoqi@0: * None of the array component can be null. To represent
aoqi@0: * the empty namespace, use the empty string "".
aoqi@0: *
aoqi@0: * @since
aoqi@0: * JAXB RI 1.0.2
aoqi@0: */
aoqi@0: public String[] getPreDeclaredNamespaceUris() {
aoqi@0: return EMPTY_STRING;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Similar to {@link #getPreDeclaredNamespaceUris()} but allows the
aoqi@0: * (prefix,nsUri) pairs to be returned.
aoqi@0: *
aoqi@0: *
aoqi@0: * With {@link #getPreDeclaredNamespaceUris()}, applications who wish to control aoqi@0: * the prefixes as well as the namespaces needed to implement both aoqi@0: * {@link #getPreDeclaredNamespaceUris()} and {@link #getPreferredPrefix(String, String, boolean)}. aoqi@0: * aoqi@0: *
aoqi@0: * This version eliminates the needs by returning an array of pairs. aoqi@0: * aoqi@0: * @return aoqi@0: * always return a non-null (but possibly empty) array. The array stores aoqi@0: * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent aoqi@0: * the empty namespace URI and the default prefix. Null is not allowed as a value aoqi@0: * in the array. aoqi@0: * aoqi@0: * @since aoqi@0: * JAXB RI 2.0 beta aoqi@0: */ aoqi@0: public String[] getPreDeclaredNamespaceUris2() { aoqi@0: return EMPTY_STRING; aoqi@0: } aoqi@0: aoqi@0: /** aoqi@0: * Returns a list of (prefix,namespace URI) pairs that represents aoqi@0: * namespace bindings available on ancestor elements (that need not be repeated aoqi@0: * by the JAXB RI.) aoqi@0: * aoqi@0: *
aoqi@0: * Sometimes JAXB is used to marshal an XML document, which will be aoqi@0: * used as a subtree of a bigger document. When this happens, it's nice aoqi@0: * for a JAXB marshaller to be able to use in-scope namespace bindings aoqi@0: * of the larger document and avoid declaring redundant namespace URIs. aoqi@0: * aoqi@0: *
aoqi@0: * This is automatically done when you are marshalling to {@link XMLStreamWriter}, aoqi@0: * {@link XMLEventWriter}, {@link DOMResult}, or {@link Node}, because aoqi@0: * those output format allows us to inspect what's currently available aoqi@0: * as in-scope namespace binding. However, with other output format, aoqi@0: * such as {@link OutputStream}, the JAXB RI cannot do this automatically. aoqi@0: * That's when this method comes into play. aoqi@0: * aoqi@0: *
aoqi@0: * Namespace bindings returned by this method will be used by the JAXB RI, aoqi@0: * but will not be re-declared. They are assumed to be available when you insert aoqi@0: * this subtree into a bigger document. aoqi@0: * aoqi@0: *
aoqi@0: * It is NOT OK to return the same binding, or give aoqi@0: * the receiver a conflicting binding information. aoqi@0: * It's a responsibility of the caller to make sure that this doesn't happen aoqi@0: * even if the ancestor elements look like: aoqi@0: *
aoqi@0: * aoqi@0: * @return aoqi@0: * always return a non-null (but possibly empty) array. The array stores aoqi@0: * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent aoqi@0: * the empty namespace URI and the default prefix. Null is not allowed as a value aoqi@0: * in the array. aoqi@0: * aoqi@0: * @since JAXB RI 2.0 beta aoqi@0: */ aoqi@0: public String[] getContextualNamespaceDecls() { aoqi@0: return EMPTY_STRING; aoqi@0: } aoqi@0: }aoqi@0: * <foo:abc xmlns:foo="abc"> aoqi@0: * <foo:abc xmlns:foo="def"> aoqi@0: * <foo:abc xmlns:foo="abc"> aoqi@0: * ... JAXB marshalling into here. aoqi@0: * </foo:abc> aoqi@0: * </foo:abc> aoqi@0: * </foo:abc> aoqi@0: *