-
- All Known Implementing Classes:
C14nXmlOutput,DOMOutput,FastInfosetStreamWriterOutput,ForkXmlOutput,IndentingUTF8XmlOutput,MTOMXmlOutput,SAXOutput,StAXExStreamWriterOutput,UTF8XmlOutput,XMLEventWriterOutput,XmlOutputAbstractImpl,XMLStreamWriterOutput
public interface XmlOutputWell-formed XML writer.Implementations of this interface is used to connect
XMLSerializerto the actual target. This allowsXMLSerializerto be API agnostic.Notes
JAXBContextassigns indices to URIs and local names that are statically known by usingNameList.XmlOutputimplementation can use these indices to improve the performance. For example, those namespace URI indices can be turned into prefixes quickly.XmlOutputstill allows arbitrary namepsace URIs / local names to be written.The
NamespaceContextImplobject, which is shared betweenXmlOutputandXMLSerializer, keeps track of the in-scope namespace bindings. By the time thebeginStartTag(org.glassfish.jaxb.runtime.v2.runtime.Name)method is called, all the namespace bindings for the new element is already declared. Similarly, after theendTag(org.glassfish.jaxb.runtime.v2.runtime.Name)method is called, in-scope bindings will be removed. This book keeping is all done outsideXmlOutput.XmlOutputandXMLSerializeruses indices to reference prefixes/URIs to be written.NamespaceContextImplcan 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", soXmlOutputis 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.
NamespaceContextImplcan handle this index correctly, but this binding will never be reported toXmlOutputthroughbeginStartTag(org.glassfish.jaxb.runtime.v2.runtime.Name).One pecurilar behavior of a
NamespaceContextImplobject is that it tries to define redundant xmlns="" on the root element. Implementations ofXmlOutputis encouraged to check for this and avoid generating redundant namespace declarations.Call Sequence
XMLSerializercalls the writer methods in the following order:CALLSEQUENCE :=
TODO: for FI, consider making attribute values from Strings to CharSequences.startDocumentELEMENTendDocument| ELEMENT // for fragment ELEMENT :=beginStartTagattribute*endStartTagCONTENTSendTagCONTENTS := (ELEMENT |text)*- Author:
- Kohsuke Kawaguchi
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidattribute(int prefix, String localName, String value)voidattribute(Name name, String value)voidbeginStartTag(int prefix, String localName)voidbeginStartTag(Name name)Writes a start tag.voidendDocument(boolean fragment)Called at the very end.voidendStartTag()voidendTag(int prefix, String localName)voidendTag(Name name)voidstartDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext)Called at the very beginning.voidtext(String value, boolean needsSeparatingWhitespace)Writes XML text with character escaping, if necessary.voidtext(Pcdata 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- theXMLSerializerthat coordinates this whole marshalling episode.fragment- true if we are marshalling a fragment.- Throws:
IOExceptionSAXExceptionXMLStreamException
-
endDocument
void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamExceptionCalled at the very end. This is the last method to be invoked.- Parameters:
fragment- false if we are writing the whole document.- Throws:
IOExceptionSAXExceptionXMLStreamException
-
beginStartTag
void beginStartTag(Name name) throws IOException, XMLStreamException
Writes a start tag.At this point
NamespaceContextImplholds namespace declarations needed for this new element.This method is used for writing tags that are indexed.
- Throws:
IOExceptionXMLStreamException
-
beginStartTag
void beginStartTag(int prefix, String localName) throws IOException, XMLStreamException- Throws:
IOExceptionXMLStreamException
-
attribute
void attribute(Name name, String value) throws IOException, XMLStreamException
- Throws:
IOExceptionXMLStreamException
-
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:
IOExceptionXMLStreamException
-
endStartTag
void endStartTag() throws IOException, SAXException- Throws:
IOExceptionSAXException
-
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:
IOExceptionSAXExceptionXMLStreamException
-
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:
IOExceptionSAXExceptionXMLStreamException
-
-