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.nbio.core.util;
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        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        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 to do
054         * namespace management yourself, independantly of the XMLWriter
055         *
056         * @param name The name of the tag.
057         */
058
059        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        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
074         * it's not 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        void attribute(String qName, String value) throws IOException;
081
082        /**
083         * Prints some textual content in an element.
084         */
085
086        void print(String data) throws IOException;
087
088        /**
089         * Prints some textual content, terminated with a newline character.
090         */
091
092        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        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        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 to
113         * 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
115         * suggested prefix for this namespace, but there is no guarantee of this.
116         * <p/>
117         * 
118         * In particular, if the namespace is already in use, the current prefix will still
119         * be used. Similarly if the suggested prefix has already been used for another
120         * namespace, a new one will be auto-generated.
121         *
122         * @param nsURI      The namespace to declare
123         * @param prefixHint A suggested prefix-string for this namespace.
124         */
125
126        void declareNamespace(String nsURI, String prefixHint) throws IOException;
127
128        /**
129         * Close this XMLWriter, and its underlying stream.
130         *
131         * @since 1.4
132         */
133
134        void close() throws IOException;
135}