001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036: package com.sun.xml.bind.marshaller;
037:
038: import java.io.OutputStream;
039:
040: import javax.xml.stream.XMLEventWriter;
041: import javax.xml.stream.XMLStreamWriter;
042: import javax.xml.transform.dom.DOMResult;
043:
044: import org.w3c.dom.Node;
045:
046: // be careful about changing this class. this class is supposed to be
047: // extended by users and therefore we are not allowed to break
048: // those user code.
049: //
050: // this means:
051: // - don't add any abstract method
052: // - don't change any existing method signature
053: // - don't remove any existing method.
054:
055: /**
056: * Implemented by the user application to determine URI -> prefix
057: * mapping.
058: *
059: * This is considered as an interface, though it's implemented
060: * as an abstract class to make it easy to add new methods in
061: * a future.
062: *
063: * @author
064: * Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
065: */
066: public abstract class NamespacePrefixMapper {
067:
068: private static final String[] EMPTY_STRING = new String[0];
069:
070: /**
071: * Returns a preferred prefix for the given namespace URI.
072: *
073: * This method is intended to be overrided by a derived class.
074: *
075: * @param namespaceUri
076: * The namespace URI for which the prefix needs to be found.
077: * Never be null. "" is used to denote the default namespace.
078: * @param suggestion
079: * When the content tree has a suggestion for the prefix
080: * to the given namespaceUri, that suggestion is passed as a
081: * parameter. Typicall this value comes from the QName.getPrefix
082: * to show the preference of the content tree. This parameter
083: * may be null, and this parameter may represent an already
084: * occupied prefix.
085: * @param requirePrefix
086: * If this method is expected to return non-empty prefix.
087: * When this flag is true, it means that the given namespace URI
088: * cannot be set as the default namespace.
089: *
090: * @return
091: * null if there's no prefered prefix for the namespace URI.
092: * In this case, the system will generate a prefix for you.
093: *
094: * Otherwise the system will try to use the returned prefix,
095: * but generally there's no guarantee if the prefix will be
096: * actually used or not.
097: *
098: * return "" to map this namespace URI to the default namespace.
099: * Again, there's no guarantee that this preference will be
100: * honored.
101: *
102: * If this method returns "" when requirePrefix=true, the return
103: * value will be ignored and the system will generate one.
104: *
105: * @since JAXB 1.0.1
106: */
107: public abstract String getPreferredPrefix(String namespaceUri,
108: String suggestion, boolean requirePrefix);
109:
110: /**
111: * Returns a list of namespace URIs that should be declared
112: * at the root element.
113: *
114: * <p>
115: * By default, the JAXB RI 1.0.x produces namespace declarations only when
116: * they are necessary, only at where they are used. Because of this
117: * lack of look-ahead, sometimes the marshaller produces a lot of
118: * namespace declarations that look redundant to human eyes. For example,
119: * <pre><xmp>
120: * <?xml version="1.0"?>
121: * <root>
122: * <ns1:child xmlns:ns1="urn:foo"> ... </ns1:child>
123: * <ns2:child xmlns:ns2="urn:foo"> ... </ns2:child>
124: * <ns3:child xmlns:ns3="urn:foo"> ... </ns3:child>
125: * ...
126: * </root>
127: * <xmp></pre>
128: *
129: * <p>
130: * The JAXB RI 2.x mostly doesn't exhibit this behavior any more,
131: * as it declares all statically known namespace URIs (those URIs
132: * that are used as element/attribute names in JAXB annotations),
133: * but it may still declare additional namespaces in the middle of
134: * a document, for example when (i) a QName as an attribute/element value
135: * requires a new namespace URI, or (ii) DOM nodes as a portion of an object
136: * tree requires a new namespace URI.
137: *
138: * <p>
139: * If you know in advance that you are going to use a certain set of
140: * namespace URIs, you can override this method and have the marshaller
141: * declare those namespace URIs at the root element.
142: *
143: * <p>
144: * For example, by returning <code>new String[]{"urn:foo"}</code>,
145: * the marshaller will produce:
146: * <pre><xmp>
147: * <?xml version="1.0"?>
148: * <root xmlns:ns1="urn:foo">
149: * <ns1:child> ... </ns1:child>
150: * <ns1:child> ... </ns1:child>
151: * <ns1:child> ... </ns1:child>
152: * ...
153: * </root>
154: * <xmp></pre>
155: * <p>
156: * To control prefixes assigned to those namespace URIs, use the
157: * {@link #getPreferredPrefix(String, String, boolean)} method.
158: *
159: * @return
160: * A list of namespace URIs as an array of {@link String}s.
161: * This method can return a length-zero array but not null.
162: * None of the array component can be null. To represent
163: * the empty namespace, use the empty string <code>""</code>.
164: *
165: * @since
166: * JAXB RI 1.0.2
167: */
168: public String[] getPreDeclaredNamespaceUris() {
169: return EMPTY_STRING;
170: }
171:
172: /**
173: * Similar to {@link #getPreDeclaredNamespaceUris()} but allows the
174: * (prefix,nsUri) pairs to be returned.
175: *
176: * <p>
177: * With {@link #getPreDeclaredNamespaceUris()}, applications who wish to control
178: * the prefixes as well as the namespaces needed to implement both
179: * {@link #getPreDeclaredNamespaceUris()} and {@link #getPreferredPrefix(String, String, boolean)}.
180: *
181: * <p>
182: * This version eliminates the needs by returning an array of pairs.
183: *
184: * @return
185: * always return a non-null (but possibly empty) array. The array stores
186: * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent
187: * the empty namespace URI and the default prefix. Null is not allowed as a value
188: * in the array.
189: *
190: * @since
191: * JAXB RI 2.0 beta
192: */
193: public String[] getPreDeclaredNamespaceUris2() {
194: return EMPTY_STRING;
195: }
196:
197: /**
198: * Returns a list of (prefix,namespace URI) pairs that represents
199: * namespace bindings available on ancestor elements (that need not be repeated
200: * by the JAXB RI.)
201: *
202: * <p>
203: * Sometimes JAXB is used to marshal an XML document, which will be
204: * used as a subtree of a bigger document. When this happens, it's nice
205: * for a JAXB marshaller to be able to use in-scope namespace bindings
206: * of the larger document and avoid declaring redundant namespace URIs.
207: *
208: * <p>
209: * This is automatically done when you are marshalling to {@link XMLStreamWriter},
210: * {@link XMLEventWriter}, {@link DOMResult}, or {@link Node}, because
211: * those output format allows us to inspect what's currently available
212: * as in-scope namespace binding. However, with other output format,
213: * such as {@link OutputStream}, the JAXB RI cannot do this automatically.
214: * That's when this method comes into play.
215: *
216: * <p>
217: * Namespace bindings returned by this method will be used by the JAXB RI,
218: * but will not be re-declared. They are assumed to be available when you insert
219: * this subtree into a bigger document.
220: *
221: * <p>
222: * It is <b>NOT</b> OK to return the same binding, or give
223: * the receiver a conflicting binding information.
224: * It's a responsibility of the caller to make sure that this doesn't happen
225: * even if the ancestor elements look like:
226: * <pre><xmp>
227: * <foo:abc xmlns:foo="abc">
228: * <foo:abc xmlns:foo="def">
229: * <foo:abc xmlns:foo="abc">
230: * ... JAXB marshalling into here.
231: * </foo:abc>
232: * </foo:abc>
233: * </foo:abc>
234: * </xmp></pre>
235: * <!-- TODO: shall we relax this constraint? -->
236: *
237: * @return
238: * always return a non-null (but possibly empty) array. The array stores
239: * data like (prefix1,nsUri1,prefix2,nsUri2,...) Use an empty string to represent
240: * the empty namespace URI and the default prefix. Null is not allowed as a value
241: * in the array.
242: *
243: * @since JAXB RI 2.0 beta
244: */
245: public String[] getContextualNamespaceDecls() {
246: return EMPTY_STRING;
247: }
248: }
|