/*
* 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.utils.xml;
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
*/
public 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
*/
public 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.
*/
public 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 openTag
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
*/
public 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 openTag
command.
*
* @param qName The name of the attribute to set
* @param value The textual value of the attribute
*/
public void attribute(String qName, String value) throws IOException;
/**
* Prints some textual content in an element.
*/
public void print(String data) throws IOException;
/**
* Prints some textual content, terminated with a newline character.
*/
public 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
*/
public void closeTag(String nsURI, String qName) throws IOException;
/**
* Closes an un-qualified element.
*
* @param name The tag name
*/
public 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 guarentee of this. 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.
*/
public void declareNamespace(String nsURI, String prefixHint) throws IOException;
/**
* Close this XMLWriter, and it's underlying stream.
*
* @since 1.4
*/
public void close() throws IOException;
}