com.sun.xml.bind.v2.runtime.output

Interface XmlOutput

public interface 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 XmlOutput method is called, all the namespace bindings for the new element is already declared. Similarly, after the XmlOutput 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 XmlOutput.

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
voidattribute(Name name, String value)
voidattribute(int prefix, String localName, String value)
voidbeginStartTag(Name name)
Writes a start tag.
voidbeginStartTag(int prefix, String localName)
voidendDocument(boolean fragment)
Called at the very end.
voidendStartTag()
voidendTag(Name name)
voidendTag(int prefix, String localName)
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

attribute

public void attribute(Name name, String value)

attribute

public void attribute(int prefix, String localName, String value)

Parameters: prefix -1 if this attribute does not have a prefix (this handling differs from that of elements.)

beginStartTag

public void beginStartTag(Name name)
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

public void beginStartTag(int prefix, String localName)

endDocument

public void endDocument(boolean fragment)
Called at the very end. This is the last method to be invoked.

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

endStartTag

public void endStartTag()

endTag

public void endTag(Name name)

endTag

public void endTag(int prefix, String localName)

startDocument

public void startDocument(XMLSerializer serializer, boolean fragment, int[] nsUriIndex2prefixIndex, NamespaceContextImpl nsContext)
Called at the very beginning.

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

text

public void text(String value, boolean needsSeparatingWhitespace)
Writes XML text with character escaping, if necessary.

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

text

public void text(Pcdata value, boolean needsSeparatingWhitespace)
Writes XML text with character escaping, if necessary.

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