001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022package org.biojava.utils.xml;
023
024import java.io.IOException;
025
026/**
027 * Simple interface for building XML documents.
028 *
029 * @author Thomas Down
030 * @since 1.3
031 */
032
033public interface XMLWriter {
034    /**
035     * Send raw data to the stream.  Mainly useful for things like DOCTYPE
036     * declarations.  Use with care!
037     *
038     * @param s a string of data to include verbatim in the XML stream
039     */
040    
041    public void printRaw(String s) throws IOException;
042    
043    /**
044     * Open a new namespace-qualified XML tag.
045     *
046     * @param nsURI A URI for the namespace to use
047     * @param localName The name of the tag
048     */
049    
050    public void openTag(String nsURI, String localName) throws IOException;
051    
052    /**
053     * Open a new unqualified XML tag.  This may also be used if you want
054     * to do namespace management yourself, independantly of the XMLWriter
055     *
056     * @param name The name of the tag.
057     */
058    
059    public void openTag(String name) throws IOException;
060    
061    /**
062     * Add an attribute to an element.  This will throw an exception if it's not
063     * called immediately after an <code>openTag</code> command.
064     *
065     * @param nsURI A URI for the namespace to use
066     * @param localName The name of the attribute
067     * @param value The textual value of the attribute
068     */
069    
070    public void attribute(String nsURI, String localName, String value) throws IOException;
071    
072    /**
073     * Add an un-qualified attribute to an element.  This will throw an exception if it's not
074     * called immediately after an <code>openTag</code> command.
075     *
076     * @param qName The name of the attribute to set
077     * @param value The textual value of the attribute
078     */
079    
080    public void attribute(String qName, String value) throws IOException;
081    
082    /**
083     * Prints some textual content in an element.
084     */
085    
086    public void print(String data) throws IOException;
087    
088    /**
089     * Prints some textual content, terminated with a newline character.
090     */
091    
092    public void println(String data) throws IOException;
093    
094    /**
095     * Closes an element
096     *
097     * @param nsURI A URI for the namespace to use
098     * @param qName The name of the tag
099     */
100    
101    public void closeTag(String nsURI, String qName) throws IOException;
102    
103    /**
104     * Closes an un-qualified element.
105     * 
106     * @param name The tag name
107     */
108    
109    public void closeTag(String name) throws IOException;
110    
111    /**
112     * Hints that a namespace is going to be used in a sub-tree.  Use this method
113     * to avoid namespaces that are used only in leaf-nodes of a tree being re-defined
114     * every time they are used.  The XMLWriter will generally try to use the suggested
115     * prefix for this namespace, but there is no guarentee of this.  In particular, if
116     * the namespace is already in use, the current prefix will still be used.  Similarly
117     * if the suggested prefix has already been used for another namespace, a new one
118     * will be auto-generated.
119     *
120     * @param nsURI The namespace to declare
121     * @param prefixHint A suggested prefix-string for this namespace.
122     */
123     
124    public void declareNamespace(String nsURI, String prefixHint) throws IOException;
125    
126    /**
127     * Close this XMLWriter, and it's underlying stream.
128     *
129     * @since 1.4
130     */
131    
132    public void close() throws IOException;
133}