com.sun.xml.bind.v2.runtime.output.XmlOutput Maven / Gradle / Ivy
Show all versions of webservices-rt Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Distribution License v. 1.0, which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
package com.sun.xml.bind.v2.runtime.output;
import java.io.IOException;
import javax.xml.bind.JAXBContext;
import javax.xml.stream.XMLStreamException;
import com.sun.xml.bind.v2.runtime.Name;
import com.sun.xml.bind.v2.runtime.NameList;
import com.sun.xml.bind.v2.runtime.XMLSerializer;
import org.xml.sax.SAXException;
/**
* Well-formed XML writer.
*
*
* Implementations of this interface is used to connect {@link XMLSerializer}
* to the actual target. This allows {@link XMLSerializer} to be API agnostic.
*
*
*
Notes
*
* {@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.
*
*
*
*
Call Sequence
*
* {@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;
}