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
022 package org.biojava3.core.util;
023
024 import java.io.IOException;
025
026 /**
027 * Simple interface for building XML documents.
028 *
029 * @author Thomas Down
030 * @since 1.3
031 */
032
033 public 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 }