- * Implementations of this interface is used to connect {@link XMLSerializer} - * to the actual target. This allows {@link XMLSerializer} to be API agnostic. - * - * - *
- * {@link JAXBContext} assigns indices to URIs and local names - * that are statically known by using {@link NameList}. - * {@link XmlOutput} implementation can use these indices to improve - * the performance. For example, those namespace URI indices can be - * turned into prefixes quickly. - * - *
- * {@link XmlOutput} still allows arbitrary namepsace URIs / local names - * to be written. - * - *
- * The {@link NamespaceContextImpl} object, which is shared between {@link XmlOutput} and - * {@link XMLSerializer}, keeps track of the in-scope namespace bindings. By the time - * the {@link #beginStartTag} method is called, all the namespace bindings for the new - * element is already declared. Similarly, after the {@link #endTag} method is called, - * in-scope bindings will be removed. This book keeping is all done outside {@link XmlOutput}. - * - *
- * {@link XmlOutput} and {@link XMLSerializer} uses indices to - * reference prefixes/URIs to be written. {@link 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 {@link 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. - * {@link NamespaceContextImpl} can handle this index correctly, but this binding will never - * be reported to {@link XmlOutput} through {@link #beginStartTag}. - * - *
- * One pecurilar behavior of a {@link NamespaceContextImpl} object is that it tries - * to define redundant xmlns="" on the root element. Implementations of {@link XmlOutput} - * is encouraged to check for this and avoid generating redundant namespace declarations. - * - * - * - *
- * {@link XMLSerializer} calls the writer methods in the following order: - * - *
- * CALLSEQUENCE := {@link #startDocument startDocument} ELEMENT {@link #endDocument endDocument}
- * | ELEMENT // for fragment
- *
- * ELEMENT := {@link #beginStartTag beginStartTag} {@link #attribute attribute}* {@link #endStartTag endStartTag} CONTENTS {@link #endTag endTag}
- *
- * CONTENTS := (ELEMENT | {@link #text text})*
- *
- *
- * TODO: for FI, consider making attribute values from Strings to CharSequences.
- *
- * @author Kohsuke Kawaguchi
- */
-public interface XmlOutput {
-//
-//
-// Contracts
-//
-//
- /**
- * Called at the very beginning.
- *
- * @param serializer
- * the {@link XMLSerializer} that coordinates this whole marshalling episode.
- * @param fragment
- * 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 end. This is the last method to be invoked.
- *
- * @param fragment
- * false if we are writing the whole document.
- */
- public void endDocument(boolean fragment) throws IOException, SAXException, XMLStreamException;
-
- /**
- * Writes a start tag.
- *
- * - * At this point {@link 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; - - public void beginStartTag(int prefix, String localName) throws IOException, XMLStreamException; - - public void attribute( Name name, String value ) throws IOException, XMLStreamException; - - /** - * @param prefix - * -1 if this attribute does not have a prefix - * (this handling differs from that of elements.) - */ - public void attribute( int prefix, String localName, String value ) throws IOException, XMLStreamException; - - public void endStartTag() throws IOException, SAXException; - - public void endTag(Name name) throws IOException, SAXException, XMLStreamException; - - public void endTag(int prefix, String localName) throws IOException, SAXException, XMLStreamException; - - /** - * Writes XML text with character escaping, if necessary. - * - * @param value - * this string can contain characters that might need escaping - * (such as {@code '&' or '>'}) - * @param needsSeparatingWhitespace - */ - public void text( String value, boolean needsSeparatingWhitespace ) throws IOException, SAXException, XMLStreamException; - - /** - * Writes XML text with character escaping, if necessary. - * - * @param value - * this string can contain characters that might need escaping - * (such as {@code '&' or '>'}) - * @param needsSeparatingWhitespace - */ - public void text( Pcdata value, boolean needsSeparatingWhitespace ) throws IOException, SAXException, XMLStreamException; -}