257 lines
10 KiB
Java
257 lines
10 KiB
Java
/*
|
|
* Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
|
|
package com.sun.xml.internal.bind.marshaller;
|
|
|
|
import java.io.OutputStream;
|
|
|
|
import javax.xml.bind.JAXBContext;
|
|
import javax.xml.stream.XMLEventWriter;
|
|
import javax.xml.stream.XMLStreamWriter;
|
|
import javax.xml.transform.dom.DOMResult;
|
|
|
|
import org.w3c.dom.Node;
|
|
|
|
// be careful about changing this class. this class is supposed to be
|
|
// extended by users and therefore we are not allowed to break
|
|
// those user code.
|
|
//
|
|
// this means:
|
|
// - don't add any abstract method
|
|
// - don't change any existing method signature
|
|
// - don't remove any existing method.
|
|
|
|
/**
|
|
* Implemented by the user application to determine URI -> prefix
|
|
* mapping.
|
|
*
|
|
* This is considered as an interface, though it's implemented
|
|
* as an abstract class to make it easy to add new methods in
|
|
* a future.
|
|
*
|
|
* @author
|
|
* Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
|
|
*/
|
|
public abstract class NamespacePrefixMapper {
|
|
|
|
private static final String[] EMPTY_STRING = new String[0];
|
|
|
|
/**
|
|
* Returns a preferred prefix for the given namespace URI.
|
|
*
|
|
* This method is intended to be overrided by a derived class.
|
|
*
|
|
* <p>
|
|
* 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:
|
|
*
|
|
* <ol>
|
|
* <li>
|
|
* If the prefix returned is already in use as one of the in-scope
|
|
* namespace bindings. This is partly necessary for correctness
|
|
* (so that we don't unexpectedly change the meaning of QNames
|
|
* bound to {@link String}), partly to simplify the marshaller.
|
|
* <li>
|
|
* If the prefix returned is "" yet the current {@link 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.
|
|
* </ol>
|
|
*
|
|
* @param namespaceUri
|
|
* The namespace URI for which the prefix needs to be found.
|
|
* Never be null. "" is used to denote the default namespace.
|
|
* @param 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.
|
|
* @param 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.
|
|
*
|
|
* @return
|
|
* null if there's no prefered 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.
|
|
*
|
|
* @since JAXB 1.0.1
|
|
*/
|
|
public abstract String getPreferredPrefix(String namespaceUri, String suggestion, boolean requirePrefix);
|
|
|
|
/**
|
|
* Returns a list of namespace URIs that should be declared
|
|
* at the root element.
|
|
*
|
|
* <p>
|
|
* 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,
|
|
* <pre><xmp>
|
|
* <?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>
|
|
* 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.
|
|
*
|
|
* <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
|
|
* {@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 <code>""</code>.
|
|
*
|
|
* @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.
|
|
*
|
|
* <p>
|
|
* 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)}.
|
|
*
|
|
* <p>
|
|
* 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.)
|
|
*
|
|
* <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 {@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.
|
|
*
|
|
* <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>
|
|
* </xmp></pre>
|
|
*
|
|
* @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;
|
|
}
|
|
}
|