2
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4
* Copyright (c) 1997-2011 Oracle and/or its affiliates. All rights reserved.
6
* The contents of this file are subject to the terms of either the GNU
7
* General Public License Version 2 only ("GPL") or the Common Development
8
* and Distribution License("CDDL") (collectively, the "License"). You
9
* may not use this file except in compliance with the License. You can
10
* obtain a copy of the License at
11
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
12
* or packager/legal/LICENSE.txt. See the License for the specific
13
* language governing permissions and limitations under the License.
15
* When distributing the software, include this License Header Notice in each
16
* file and include the License file at packager/legal/LICENSE.txt.
18
* GPL Classpath Exception:
19
* Oracle designates this particular file as subject to the "Classpath"
20
* exception as provided by Oracle in the GPL Version 2 section of the License
21
* file that accompanied this code.
24
* If applicable, add the following below the License Header, with the fields
25
* enclosed by brackets [] replaced by your own identifying information:
26
* "Portions Copyright [year] [name of copyright owner]"
29
* If you wish your version of this file to be governed by only the CDDL or
30
* only the GPL Version 2, indicate your decision by adding "[Contributor]
31
* elects to include this software in this distribution under the [CDDL or GPL
32
* Version 2] license." If you don't indicate a single choice of license, a
33
* recipient has the option to distribute your version of this file under
34
* either the CDDL, the GPL Version 2 or to extend the choice of license to
35
* its licensees as provided above. However, if you add GPL Version 2 code
36
* and therefore, elected the GPL Version 2 license, then the option applies
37
* only if the new code is made subject to such option by the copyright
41
package com.sun.xml.bind.v2.runtime.output;
43
import java.io.IOException;
45
import javax.xml.bind.JAXBContext;
46
import javax.xml.stream.XMLStreamException;
48
import com.sun.xml.bind.v2.runtime.Name;
49
import com.sun.xml.bind.v2.runtime.NameList;
50
import com.sun.xml.bind.v2.runtime.XMLSerializer;
52
import org.xml.sax.SAXException;
55
* Well-formed XML writer.
58
* Implementations of this interface is used to connect {@link XMLSerializer}
59
* to the actual target. This allows {@link XMLSerializer} to be API agnostic.
64
* {@link JAXBContext} assigns indices to URIs and local names
65
* that are statically known by using {@link NameList}.
66
* {@link XmlOutput} implementation can use these indices to improve
67
* the performance. For example, those namespace URI indices can be
68
* turned into prefixes quickly.
71
* {@link XmlOutput} still allows arbitrary namepsace URIs / local names
75
* The {@link NamespaceContextImpl} object, which is shared between {@link XmlOutput} and
76
* {@link XMLSerializer}, keeps track of the in-scope namespace bindings. By the time
77
* the {@link #beginStartTag} method is called, all the namespace bindings for the new
78
* element is already declared. Similarly, after the {@link #endTag} method is called,
79
* in-scope bindings will be removed. This book keeping is all done outside {@link XmlOutput}.
82
* {@link XmlOutput} and {@link XMLSerializer} uses indices to
83
* reference prefixes/URIs to be written. {@link NamespaceContextImpl} can
84
* convert prefix indices to URIs and the string representations of prefixes.
85
* Binding from indices to URIs and prefixes do not change while indices
86
* are "in scope", so {@link XmlOutput} is again expected to take advantage of
87
* this to improve the perofmrnace.
90
* prefix index 0 is reserved for "xml", and this binding is assumed to be always there.
91
* {@link NamespaceContextImpl} can handle this index correctly, but this binding will never
92
* be reported to {@link XmlOutput} through {@link #beginStartTag}.
95
* One pecurilar behavior of a {@link NamespaceContextImpl} object is that it tries
96
* to define redundant xmlns="" on the root element. Implementations of {@link XmlOutput}
97
* is encouraged to check for this and avoid generating redundant namespace declarations.
101
* <h2>Call Sequence</h2>
103
* {@link XMLSerializer} calls the writer methods in the following order:
106
* CALLSEQUENCE := {@link #startDocument startDocument} ELEMENT {@link #endDocument endDocument}
107
* | ELEMENT // for fragment
109
* ELEMENT := {@link #beginStartTag beginStartTag} {@link #attribute attribute}* {@link #endStartTag endStartTag} CONTENTS {@link #endTag endTag}
111
* CONTENTS := (ELEMENT | {@link #text text})*
114
* TODO: for FI, consider making attribute values from Strings to CharSequences.
116
* @author Kohsuke Kawaguchi
118
public interface XmlOutput {
125
* Called at the very beginning.
128
* the {@link XMLSerializer} that coordinates this whole marshalling episode.
130
* true if we are marshalling a fragment.
132
public void startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext) throws IOException, SAXException, XMLStreamException;
135
* Called at the very end. This is the last method to be invoked.
138
* false if we are writing the whole document.
140
public void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamException;
143
* Writes a start tag.
146
* At this point {@link NamespaceContextImpl} holds namespace declarations needed for this
150
* This method is used for writing tags that are indexed.
152
public void beginStartTag(Name name) throws IOException, XMLStreamException;
154
public void beginStartTag(int prefix, String localName) throws IOException, XMLStreamException;
156
public void attribute( Name name, String value ) throws IOException, XMLStreamException;
160
* -1 if this attribute does not have a prefix
161
* (this handling differs from that of elements.)
163
public void attribute( int prefix, String localName, String value ) throws IOException, XMLStreamException;
165
public void endStartTag() throws IOException, SAXException;
167
public void endTag(Name name) throws IOException, SAXException, XMLStreamException;
169
public void endTag(int prefix, String localName) throws IOException, SAXException, XMLStreamException;
172
* Writes XML text with character escaping, if necessary.
175
* this string can contain characters that might need escaping
176
* (such as '&' or '>')
177
* @param needsSeparatingWhitespace
179
public void text( String value, boolean needsSeparatingWhitespace ) throws IOException, SAXException, XMLStreamException;
182
* Writes XML text with character escaping, if necessary.
185
* this string can contain characters that might need escaping
186
* (such as '&' or '>')
187
* @param needsSeparatingWhitespace
189
public void text( Pcdata value, boolean needsSeparatingWhitespace ) throws IOException, SAXException, XMLStreamException;