/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2015 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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.
*
* <p>
* Implementations of this interface is used to connect {@link XMLSerializer}
* to the actual target. This allows {@link XMLSerializer} to be API agnostic.
*
*
* <h2>Notes</h2>
* <p>
* {@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.
*
* <p>
* {@link XmlOutput} still allows arbitrary namepsace URIs / local names
* to be written.
*
* <p>
* 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}.
*
* <p>
* {@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.
*
* <p>
* 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}.
*
* <p>
* 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.
*
*
*
* <h2>Call Sequence</h2>
* <p>
* {@link XMLSerializer} calls the writer methods in the following order:
*
* <pre>
* 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})*
* </pre>
*
* 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.
*
* <p>
* At this point {@link NamespaceContextImpl} holds namespace declarations needed for this
* new element.
*
* <p>
* 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;
}