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        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}