xmlwriter.java

这是外国一个开源推理机

/*  Sesame - Storage and Querying architecture for RDF and RDF Schema
 *  Copyright (C) 2001-2005 Aduna
 *
 *  Contact:
 *  	Aduna
 *  	Prinses Julianaplein 14 b
 *  	3817 CS Amersfoort
 *  	The Netherlands
 *  	tel. [phone]
 *  	fax. [phone]
 *
 *  	http://aduna.biz/
 *  	http://www.openrdf.org/
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.openrdf.util.xml;

import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.util.ArrayList;
import java.util.HashMap;

/**
 * A utility class offering convenience methods for writing XML. This class
 * takes care of character escaping, identation, etc. This class does not verify
 * that the written data is legal XML. It is the callers responsibility to make
 * sure that elements are properly nested, etc.
 *
 * <h3>Example:</h3>
 * <p>
 * To write the following XML:
 * <pre>
 * &lt;?xml version='1.0' encoding='UTF-8'?&gt;
 * &lt;xml-doc&gt;
 *	&lt;foo a="1" b="2&amp;amp;3"/&gt;
 *	&lt;bar&gt;Hello World!&lt;/bar&gt;
 * &lt;/xml-doc&gt;
 *</pre>
 * <p>
 * One can use the following code:
 * <pre>
 * XmlQueryResultWriter xmlWriter = new XmlQueryResultWriter(myWriter);
 * xmlWriter.setPrettyPrint(true);
 *
 * xmlWriter.startDocument();
 * xmlWriter.startTag("xml-doc");
 *
 * xmlWriter.setAttribute("a", 1);
 * xmlWriter.setAttribute("b", "2&amp;3");
 * xmlWriter.simpleTag("foo");
 *
 * xmlWriter.textTag("bar", "Hello World!");
 *
 * xmlWriter.endTag("xml-doc");
 * xmlWriter.endDocument();
 * </pre>
 **/
public class XmlWriter {

/*-------------------------------------------+
| Constants                                  |
+-------------------------------------------*/

	/**
	 * The (platform-dependent) line separator.
	 **/
	private static final String LINE_SEPARATOR =
			System.getProperty("line.separator");

/*-------------------------------------------+
| Variables                                  |
+-------------------------------------------*/

	/**
	 * A wrapper around an OutputStream that handles the character
	 * encoding.
	 **/
	private Writer _writer;

	/**
	 * The required character encoding of the written data.
	 **/
	private String _charEncoding;

	/**
	 * Flag indicating whether the output should be printed pretty,
	 * i.e. adding newlines and indentation.
	 **/
	private boolean _prettyPrint = false;

	/**
	 * The current indentation level, i.e. the number of tabs to
	 * indent a start or end tag.
	 **/
	private int _indentLevel = 0;

	/**
	 * The string to use for indentation, e.g. a tab or a number of spaces.
	 **/
	private String _indentString = "\t";

	/**
	 * The names of the attributes for the next start tag. This list
	 * contains objects of type <tt>String</tt>.
	 **/
	private ArrayList _attNames = new ArrayList();

	/**
	 * A mapping from attribute names to values for the next start
	 * tag. Both key and value are of type <tt>String</tt>
	 **/
	private HashMap _attValues = new HashMap();

/*-------------------------------------------+
| Constructors                               |
+-------------------------------------------*/

	/**
	 * Creates a new XmlQueryResultWriter that will write its data to the
	 * supplied Writer. Character encoding issues are left to the
	 * supplier of the Writer.
	 *
	 * @param writer The Writer to write the XML to.
	 **/
	
	public XmlWriter(Writer writer) {
		_writer = writer;
	}

	/**
	 * Creates a new XmlQueryResultWriter that will write its data to the
	 * supplied OutputStream in the default UTF-8 character
	 * encoding.
	 *
	 * @param outputStream The OutputStream to write the XML to.
	 **/
	public XmlWriter(OutputStream outputStream) {
		try {
			_charEncoding = "UTF-8";
			_writer = new OutputStreamWriter(outputStream, _charEncoding);
		}
		catch (UnsupportedEncodingException e) {
			// UTF-8 must be supported by all compliant JVM's,
			// this exception should never be thrown.
			throw new RuntimeException(
					"UTF-8 character encoding not supported on this platform");
		}
	}

	/**
	 * Creates a new XmlQueryResultWriter that will write its data to the
	 * supplied OutputStream in specified character encoding.
	 *
	 * @param outputStream The OutputStream to write the XML to.
	 **/
	public XmlWriter(OutputStream outputStream, String charEncoding)
		throws UnsupportedEncodingException
	{
		_charEncoding = charEncoding;
		_writer = new OutputStreamWriter(outputStream, _charEncoding);
	}

/*-------------------------------------------+
| Methods                                    |
+-------------------------------------------*/

	/**
	 * Enables or disables pretty-printing. If pretty-printing is
	 * enabled, the XmlQueryResultWriter will add newlines and indentation to the
	 * written data. Pretty-printing is disabled by default.
	 *
	 * @param prettyPrint Flag indicating whether pretty-printing
	 * should be enabled.
	 **/
	public void setPrettyPrint(boolean prettyPrint) {
		_prettyPrint = prettyPrint;
	}

	/**
	 * Checks whether pretty-printing is enabled.
	 *
	 * @return <tt>true</tt> if pretty-printing is enabled,
	 * <tt>false</tt> otherwise.
	 **/
	public boolean prettyPrintEnabled() {
		return _prettyPrint;
	}

	/**
	 * Sets the string that should be used for indentation when
	 * pretty-printing is enabled. The default indentation string
	 * is a tab character.
	 *
	 * @param indentString The indentation string, e.g. a tab or a
	 * number of spaces.
	 **/
	public void setIndentString(String indentString) {
		_indentString = indentString;
	}

	/**
	 * Gets the string used for indentation.
	 *
	 * @return the indentation string.
	 **/
	public String getIndentString() {
		return _indentString;
	}

	/**
	 * Writes the XML header for the XML file.
	 *
	 * @exception IOException If an I/O error occurs.
	 **/
	public void startDocument()
		throws IOException
	{
		_write("<?xml version='1.0'");
		if (_charEncoding != null) {
			_write(" encoding='" + _charEncoding + "'");
		}
		_writeLn("?>");
	}

	/**
	 * Finishes writing and flushes the OutputStream or Writer that
	 * this XmlQueryResultWriter is writing to.
	 **/
	public void endDocument()
		throws IOException
	{
		_writer.flush();
		_writer = null;
	}

	/**
	 * Sets an attribute for the next start tag.
	 *
	 * @param name The name of the attribute.
	 * @param value The value of the attribute.
	 **/
	public void setAttribute(String name, String value) {
		_attNames.add(name);
		_attValues.put(name, value);
	}

	/**
	 * Sets an attribute for the next start element.
	 *
	 * @param name The name of the attribute.
	 * @param value The value of the attribute. The integer value
	 * will be transformed to a string using the method
	 * <tt>String.valueOf(int)</tt>.
	 * @see java.lang.String#valueOf(int)
	 **/
	public void setAttribute(String name, int value) {
		setAttribute(name, String.valueOf(value));
	}

	/**
	 * Sets an attribute for the next start element.
	 *
	 * @param name The name of the attribute.
	 * @param value The value of the attribute. The boolean value
	 * will be transformed to a string using the method
	 * <tt>String.valueOf(boolean)</tt>.
	 * @see java.lang.String#valueOf(boolean)
	 **/
	public void setAttribute(String name, boolean value) {
		setAttribute(name, String.valueOf(value));
	}

	/**
	 * Writes a start tag containing the previously set attributes.
	 *
	 * @param elName The element name.
	 * @see #setAttribute(java.lang.String,java.lang.String)
	 **/
	public void startTag(String elName)
		throws IOException
	{
		_writeIndent();
		_write("<" + elName);
		_writeAtts();
		_writeLn(">");
		_indentLevel++;
	}

	/**
	 * Writes an end tag.
	 *
	 * @param elName The element name.
	 **/
	public void endTag(String elName)
		throws IOException
	{
		_indentLevel--;
		_writeIndent();
		_writeLn("</" + elName + ">");
	}

	/**
	 * Writes an 'empty' element, e.g. <tt>&lt;foo/&gt;</tt>. The
	 * tag will contain any previously set attributes.
	 *
	 * @param elName The element name.
	 * @see #setAttribute(java.lang.String,java.lang.String)
	 **/
	public void emptyElement(String elName)
		throws IOException
	{
		_writeIndent();
		_write("<" + elName);
		_writeAtts();
		_writeLn("/>");
	}

	/**
	 * Writes a start and end tag with the supplied text between them.
	 * The start tag will contain any previously set attributes.
	 *
	 * @param elName The element name.
	 * @param text The text.
	 * @see #setAttribute(java.lang.String,java.lang.String)
	 **/
	public void textElement(String elName, String text)
		throws IOException
	{
		_writeIndent();
		_write("<" + elName);
		_writeAtts();
		_write(">");
		text(text);
		_writeLn("</" + elName + ">");
	}

	/**
	 * Writes a start and end tag with the supplied text between them,
	 * without the usual escape rules.
	 * The start tag will contain any previously set attributes.
	 *
	 * @param elName The element name.
	 * @param text The text.
	 * @see #setAttribute(java.lang.String,java.lang.String)
	 **/
	public void unescapedTextElement(String elName, String text)
		throws IOException
	{
		_writeIndent();
		_write("<" + elName);
		_writeAtts();
		_write(">");
		_write(text);
		_writeLn("</" + elName + ">");
	}

	/**
	 * Writes a start and end tag with the supplied value between them.
	 * The start tag will contain any previously set attributes.
	 *
	 * @param elName The element name.
	 * @param value The value. The integer value will be transformed
	 * to a string using the method <tt>String.valueOf(int)</tt>.
	 * @see java.lang.String#valueOf(int)
	 **/
	public void textElement(String elName, int value)
		throws IOException
	{
		textElement(elName, String.valueOf(value));
	}

	/**
	 * Writes a start and end tag with the supplied boolean value
	 * between them. The start tag will contain any previously set
	 * attributes.
	 *
	 * @param elName The element name.
	 * @param value The boolean value. The integer value will be
	 * transformed to a string using the method
	 * <tt>String.valueOf(boolean)</tt>.
	 * @see java.lang.String#valueOf(boolean)
	 **/
	public void textElement(String elName, boolean value)
		throws IOException
	{
		textElement(elName, String.valueOf(value));
	}

	/**
	 * Writes a piece of text.
	 *
	 * @param text The text.
	 **/
	public void text(String text)
		throws IOException
	{
		_write(XmlUtil.escapeChars(text));
	}

	/**
	 * Writes a comment.
	 *
	 * @param comment The comment.
	 **/
	public void comment(String comment)
		throws IOException
	{
		_writeIndent();
		_writeLn("<!-- " + comment + " -->");
	}

	/**
	 * Writes an empty line. A call to this method will be ignored
	 * when pretty-printing is disabled.
	 *
	 * @see #setPrettyPrint
	 **/
	public void emptyLine()
		throws IOException
	{
		_writeLn("");
	}

	/**
	 * Writes any set attributes and clears them afterwards.
	 **/
	private void _writeAtts()
		throws IOException
	{
		for (int i = 0; i < _attNames.size(); i++) {
			String name = (String)_attNames.get(i);
			String value = (String)_attValues.get(name);

			_write(" " + name + "='");
			if (value != null) {
				_write(XmlUtil.escapeChars(value));
			}
			_write("'");
		}
		
		_attNames.clear();
		_attValues.clear();
	}

	/**
	 * Writes a string.
	 **/
	protected void _write(String s)
		throws IOException
	{
		_writer.write(s);
	}

	/**
	 * Writes a string followed by a line-separator. The
	 * line-separator is not written when pretty-printing is
	 * disabled.
	 **/
	protected void _writeLn(String s)
		throws IOException
	{
		_write(s);
		if (_prettyPrint) {
			_writer.write(LINE_SEPARATOR);
		}
	}

	/**
	 * Writes as much indentation strings as appropriate for the
	 * current indentation level. A call to this method is ignored
	 * when pretty-printing is disabled.
	 **/
	protected void _writeIndent()
		throws IOException
	{
		if (_prettyPrint) {
			for (int i = 0; i < _indentLevel; i++) {
				_writer.write(_indentString);
			}
		}
	}
}