- * 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, - *
{@code
- *
- *
- * ...
- * ...
- * ...
- * ...
- *
- * }
- *
- * - * 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:
- *
{@code
- *
- *
- * ...
- * ...
- * ...
- * ...
- *
- * }
- *
- * 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: - *
{@code
- *
- *
- *
- * ... JAXB marshalling into here.
- *
- *
- *
- * }
- *
- * @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;
- }
-}