/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */

package org.biojava.nbio.core.util;

import java.io.IOException;

/**
 * Simple interface for building XML documents.
 *
 * @author Thomas Down
 * @since 1.3
 */

public interface XMLWriter {
	/**
	 * Send raw data to the stream. Mainly useful for things like DOCTYPE
	 * declarations. Use with care!
	 *
	 * @param s a string of data to include verbatim in the XML stream
	 */

	void printRaw(String s) throws IOException;

	/**
	 * Open a new namespace-qualified XML tag.
	 *
	 * @param nsURI     A URI for the namespace to use
	 * @param localName The name of the tag
	 */

	void openTag(String nsURI, String localName) throws IOException;

	/**
	 * Open a new unqualified XML tag. This may also be used if you want to do
	 * namespace management yourself, independantly of the XMLWriter
	 *
	 * @param name The name of the tag.
	 */

	void openTag(String name) throws IOException;

	/**
	 * Add an attribute to an element. This will throw an exception if it's not
	 * called immediately after an <code>openTag</code> command.
	 *
	 * @param nsURI     A URI for the namespace to use
	 * @param localName The name of the attribute
	 * @param value     The textual value of the attribute
	 */

	void attribute(String nsURI, String localName, String value) throws IOException;

	/**
	 * Add an un-qualified attribute to an element. This will throw an exception if
	 * it's not called immediately after an <code>openTag</code> command.
	 *
	 * @param qName The name of the attribute to set
	 * @param value The textual value of the attribute
	 */

	void attribute(String qName, String value) throws IOException;

	/**
	 * Prints some textual content in an element.
	 */

	void print(String data) throws IOException;

	/**
	 * Prints some textual content, terminated with a newline character.
	 */

	void println(String data) throws IOException;

	/**
	 * Closes an element
	 *
	 * @param nsURI A URI for the namespace to use
	 * @param qName The name of the tag
	 */

	void closeTag(String nsURI, String qName) throws IOException;

	/**
	 * Closes an un-qualified element.
	 *
	 * @param name The tag name
	 */

	void closeTag(String name) throws IOException;

	/**
	 * Hints that a namespace is going to be used in a sub-tree. Use this method to
	 * avoid namespaces that are used only in leaf-nodes of a tree being re-defined
	 * every time they are used. The XMLWriter will generally try to use the
	 * suggested prefix for this namespace, but there is no guarantee of this.
	 * <p>
	 * 
	 * In particular, if the namespace is already in use, the current prefix will still
	 * be used. Similarly if the suggested prefix has already been used for another
	 * namespace, a new one will be auto-generated.
	 *
	 * @param nsURI      The namespace to declare
	 * @param prefixHint A suggested prefix-string for this namespace.
	 */

	void declareNamespace(String nsURI, String prefixHint) throws IOException;

	/**
	 * Close this XMLWriter, and its underlying stream.
	 *
	 * @since 1.4
	 */

	void close() throws IOException;
}
