JAXB OSGI 4.0.9 · org.glassfish.jaxb.runtime.v2.runtime.output.XmlOutput

Well-formed XML writer.

Implementations of this interface is used to connect XMLSerializer to the actual target. This allows XMLSerializer to be API agnostic.

Notes

JAXBContext assigns indices to URIs and local names that are statically known by using NameList. 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 between XmlOutput and XMLSerializer, keeps track of the in-scope namespace bindings. By the time the beginStartTag method is called, all the namespace bindings for the new element is already declared. Similarly, after the endTag method is called, in-scope bindings will be removed. This book keeping is all done outside XmlOutput.

XmlOutput and XMLSerializer 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", so XmlOutput 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 to XmlOutput through beginStartTag.

One pecurilar behavior of a NamespaceContextImpl object is that it tries to define redundant xmlns="" on the root element. Implementations of XmlOutput is encouraged to check for this and avoid generating redundant namespace declarations.

Call Sequence

XMLSerializer calls the writer methods in the following order:

CALLSEQUENCE  :=  startDocument ELEMENT endDocument
              |   ELEMENT   // for fragment

ELEMENT       :=  beginStartTag attribute* endStartTag CONTENTS endTag

CONTENTS      :=  (ELEMENT | text)*

Todo

for FI, consider making attribute values from Strings to CharSequences.

Method Summary

Modifier and Type	Method and Description
public void	attribute(Name name, String value)
public void	attribute(int -1 if this attribute does not have a prefix (this handling differs from that of elements.) prefix, String localName, String value)
public void	beginStartTag(Name name) Writes a start tag.
public void	beginStartTag(int prefix, String localName)
public void	endDocument(boolean false if we are writing the whole document. fragment) Called at the very end.
public void	endStartTag()
public void	endTag(Name name)
public void	endTag(int prefix, String localName)
public void	startDocument(XMLSerializer the `XMLSerializer` that coordinates this whole marshalling episode. serializer, boolean true if we are marshalling a fragment. fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext) Called at the very beginning.
public void	text(String this string can contain characters that might need escaping (such as `'&' or '>'`) value, boolean needsSeparatingWhitespace) Writes XML text with character escaping, if necessary.
public void	text(Pcdata this string can contain characters that might need escaping (such as `'&' or '>'`) value, boolean needsSeparatingWhitespace) Writes XML text with character escaping, if necessary.

Method Detail

attribute	back to summary
public void attribute(Name name, String value) throws IOException, XMLStreamException

attribute	back to summary
public void attribute(int prefix, String localName, String value) throws IOException, XMLStreamException Parameters prefix:int -1 if this attribute does not have a prefix (this handling differs from that of elements.)

beginStartTag back to summary

beginStartTag	back to summary
public 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.

public 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.

beginStartTag	back to summary
public void beginStartTag(int prefix, String localName) throws IOException, XMLStreamException

endDocument	back to summary
public void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamException Called at the very end. This is the last method to be invoked. Parameters fragment:boolean false if we are writing the whole document.

endDocument

back to summary

public void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamException

Called at the very end. This is the last method to be invoked.

Parameters

fragment:boolean: false if we are writing the whole document.

endStartTag	back to summary
public void endStartTag() throws IOException, SAXException

endTag	back to summary
public void endTag(Name name) throws IOException, SAXException, XMLStreamException

endTag	back to summary
public void endTag(int prefix, String localName) throws IOException, SAXException, XMLStreamException

startDocument back to summary

startDocument	back to summary
public void startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext) throws IOException, SAXException, XMLStreamException Called at the very beginning. Parameters serializer:XMLSerializer the `XMLSerializer` that coordinates this whole marshalling episode. fragment:boolean true if we are marshalling a fragment.

public void startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext) throws IOException, SAXException, XMLStreamException

Called at the very beginning.

Parameters

serializer:XMLSerializer: the XMLSerializer that coordinates this whole marshalling episode.
fragment:boolean: true if we are marshalling a fragment.

text back to summary

text	back to summary
public void text(String value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException Writes XML text with character escaping, if necessary. Parameters value:String this string can contain characters that might need escaping (such as `'&' or '>'`)

public void text(String value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException

Writes XML text with character escaping, if necessary.

Parameters

value:String: this string can contain characters that might need escaping (such as '&' or '>')

text back to summary

text	back to summary
public void text(Pcdata value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException Writes XML text with character escaping, if necessary. Parameters value:Pcdata this string can contain characters that might need escaping (such as `'&' or '>'`)

public void text(Pcdata value, boolean needsSeparatingWhitespace) throws IOException, SAXException, XMLStreamException

Writes XML text with character escaping, if necessary.

Parameters

value:Pcdata: this string can contain characters that might need escaping (such as '&' or '>')

public Interface XmlOutput

Notes

Call Sequence

Method Summary

Method Detail