Interface XmlOutput
-
- All Known Implementing Classes:
C14nXmlOutput
,DOMOutput
,FastInfosetStreamWriterOutput
,ForkXmlOutput
,IndentingUTF8XmlOutput
,MTOMXmlOutput
,SAXOutput
,StAXExStreamWriterOutput
,UTF8XmlOutput
,XMLEventWriterOutput
,XmlOutputAbstractImpl
,XMLStreamWriterOutput
public interface XmlOutput
Well-formed XML writer.Implementations of this interface is used to connect
XMLSerializer
to the actual target. This allowsXMLSerializer
to be API agnostic.Notes
JAXBContext
assigns indices to URIs and local names that are statically known by usingNameList
.XmlOutput
implementation can use these indices to improve the performance. For example, those namespace URI indices can be turned into prefixes quickly.XmlOutput
still allows arbitrary namepsace URIs / local names to be written.The
NamespaceContextImpl
object, which is shared betweenXmlOutput
andXMLSerializer
, keeps track of the in-scope namespace bindings. By the time thebeginStartTag(com.sun.xml.bind.v2.runtime.Name)
method is called, all the namespace bindings for the new element is already declared. Similarly, after theendTag(com.sun.xml.bind.v2.runtime.Name)
method is called, in-scope bindings will be removed. This book keeping is all done outsideXmlOutput
.XmlOutput
andXMLSerializer
uses indices to reference prefixes/URIs to be written.NamespaceContextImpl
can convert prefix indices to URIs and the string representations of prefixes. Binding from indices to URIs and prefixes do not change while indices are "in scope", soXmlOutput
is again expected to take advantage of this to improve the perofmrnace.prefix index 0 is reserved for "xml", and this binding is assumed to be always there.
NamespaceContextImpl
can handle this index correctly, but this binding will never be reported toXmlOutput
throughbeginStartTag(com.sun.xml.bind.v2.runtime.Name)
.One pecurilar behavior of a
NamespaceContextImpl
object is that it tries to define redundant xmlns="" on the root element. Implementations ofXmlOutput
is encouraged to check for this and avoid generating redundant namespace declarations.Call Sequence
XMLSerializer
calls the writer methods in the following order:CALLSEQUENCE :=
TODO: for FI, consider making attribute values from Strings to CharSequences.startDocument
ELEMENTendDocument
| ELEMENT // for fragment ELEMENT :=beginStartTag
attribute
*endStartTag
CONTENTSendTag
CONTENTS := (ELEMENT |text
)*- Author:
- Kohsuke Kawaguchi
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
attribute(int prefix, String localName, String value)
void
attribute(Name name, String value)
void
beginStartTag(int prefix, String localName)
void
beginStartTag(Name name)
Writes a start tag.void
endDocument(boolean fragment)
Called at the very end.void
endStartTag()
void
endTag(int prefix, String localName)
void
endTag(Name name)
void
startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext)
Called at the very beginning.void
text(Pcdata value, boolean needsSeparatingWhitespace)
Writes XML text with character escaping, if necessary.void
text(String value, boolean needsSeparatingWhitespace)
Writes XML text with character escaping, if necessary.
-
-
-
Method Detail
-
startDocument
void startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext) throws IOException, SAXException, XMLStreamException
Called at the very beginning.- Parameters:
serializer
- theXMLSerializer
that coordinates this whole marshalling episode.fragment
- true if we are marshalling a fragment.- Throws:
IOException
SAXException
XMLStreamException
-
endDocument
void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamException
Called at the very end. This is the last method to be invoked.- Parameters:
fragment
- false if we are writing the whole document.- Throws:
IOException
SAXException
XMLStreamException
-
beginStartTag
void beginStartTag(Name name) throws IOException, XMLStreamException
Writes a start tag.At this point
NamespaceContextImpl
holds namespace declarations needed for this new element.This method is used for writing tags that are indexed.
- Throws:
IOException
XMLStreamException
-
beginStartTag
void beginStartTag(int prefix, String localName) throws IOException, XMLStreamException
- Throws:
IOException
XMLStreamException
-
attribute
void attribute(Name name, String value) throws IOException, XMLStreamException
- Throws:
IOException
XMLStreamException
-
attribute
void attribute(int prefix, String localName, String value) throws IOException, XMLStreamException
- Parameters:
prefix
- -1 if this attribute does not have a prefix (this handling differs from that of elements.)- Throws:
IOException
XMLStreamException
-
endStartTag
void endStartTag() throws IOException, SAXException
- Throws:
IOException
SAXException
-
endTag
void endTag(Name name) throws IOException, SAXException, XMLStreamException
-
endTag
void endTag(int prefix, String localName) throws IOException, SAXException, XMLStreamException
-
text
void text(String value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException
Writes XML text with character escaping, if necessary.- Parameters:
value
- this string can contain characters that might need escaping (such as'&' or '>'
)needsSeparatingWhitespace
-- Throws:
IOException
SAXException
XMLStreamException
-
text
void text(Pcdata value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException
Writes XML text with character escaping, if necessary.- Parameters:
value
- this string can contain characters that might need escaping (such as'&' or '>'
)needsSeparatingWhitespace
-- Throws:
IOException
SAXException
XMLStreamException
-
-