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

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 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(com.sun.xml.bind.v2.runtime.Name) method is called, all the namespace bindings for the new element is already declared. Similarly, after the endTag(com.sun.xml.bind.v2.runtime.Name) 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(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 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.

Author:

Kohsuke Kawaguchi

Method Summary

Modifier and Type	Method and 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 - the XMLSerializer 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

Throws:

IOException

SAXException

XMLStreamException

endTag

void endTag(int prefix,
            String localName)
     throws IOException,
            SAXException,
            XMLStreamException

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