edu.isi.pegasus.common.util
Class XMLOutput

java.lang.Object
  edu.isi.pegasus.common.util.XMLOutput

public abstract class XMLOutput
extends Object

This abstract class defines a common base for certain classes that deal with the generation of XML files. Historically, this class also dealt with text generation, but those methods have been mostly removed.

Version:

$Revision: 2574 $

Author:

Jens-S. Vöckler

Constructor Summary

XMLOutput()

Method Summary

static String	escape(String original) Escapes certain characters inappropriate for textual output.
static String	quote(String original, boolean isAttribute) Escapes certain characters inappropriate for XML content output.
String	toXML(String indent, String namespace) Dumps the state of the current element as XML output.
void	toXML(Writer stream, String indent) Convenience adaptor method invoking the equivalent of:
abstract void	toXML(Writer stream, String indent, String namespace) Dump the state of the current element as XML output.
void	writeAttribute(Writer stream, String key, String value) XML write helper method writes a quoted attribute onto a stream.
void	writeAttribute2(Writer stream, String key, String value) Saner XML write helper method writes a quoted attribute onto a stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLOutput

public XMLOutput()

Method Detail

escape

public static String escape(String original)

Escapes certain characters inappropriate for textual output. Since this method does not hurt, and may be useful in other regards, it will be retained for now.

Parameters:

original - is a string that needs to be quoted

Returns:

a string that is "safe" to print.

quote

public static String quote(String original,
                           boolean isAttribute)

Escapes certain characters inappropriate for XML content output. According to the XML 1.0 Specification, an attribute cannot contain ampersand, percent, nor the character that was used to quote the attribute value.

Parameters:

original - is a string that needs to be quoted

isAttribute - denotes an attributes value, if set to true. If false, it denotes regular XML content outside of attributes.

Returns:

a string that is "safe" to print as XML.

writeAttribute

public void writeAttribute(Writer stream,
                           String key,
                           String value)
                    throws IOException

XML write helper method writes a quoted attribute onto a stream. The terminating quote will be appended automatically. Values will be XML-escaped. No action will be taken, if the value is null.

Parameters:

stream - is the stream to append to

key - is the attribute including initial space, attribute name, equals sign, and opening quote. The string passed as key must never be null.

value - is a string value, which will be put within the quotes and which will be escaped. If the value is null, no action will be taken

Throws:

IOException - for stream errors.

writeAttribute2

public void writeAttribute2(Writer stream,
                            String key,
                            String value)
                     throws IOException

Saner XML write helper method writes a quoted attribute onto a stream. The value will be put properly into quotes. Values will be XML-escaped. No action will be taken, if the key or value are null.

Parameters:

stream - is the stream to append to

key - is the attribute identifier, and just that.

value - is a string value, which will be put within the quotes and which will be escaped. If the value is null, no action will be taken.

Throws:

IOException - for stream errors.

toXML

public String toXML(String indent,
                    String namespace)
             throws IOException

Dumps the state of the current element as XML output. This function traverses all sibling classes as necessary, and converts the data into pretty-printed XML output.

Sibling classes which represent small leaf objects, and can return the necessary data more efficiently, are encouraged to overwrite this method.

Parameters:

indent - is a String of spaces used for pretty printing. The initial amount of spaces should be an empty string. The parameter is used internally for the recursive traversal. If null, avoidable whitespaces in the output will be avoided.

namespace - is the XML schema namespace prefix. If neither empty nor null, each element will be prefixed with this prefix, and the root element will map the XML namespace.

Returns:

a String which contains the state of the current class and its siblings using XML. Note that these strings might become large.

Throws:

IOException - when encountering an error constructing the string.

toXML

public void toXML(Writer stream,
                  String indent)
           throws IOException

Convenience adaptor method invoking the equivalent of:

 toXML( stream, indent, (String) null );
 

Parameters:

stream - is a stream opened and ready for writing. This can also be a string stream for efficient output.

indent - is a String of spaces used for pretty printing. The initial amount of spaces should be an empty string. The parameter is used internally for the recursive traversal. If a null value is specified, no indentation nor linefeeds will be generated.

Throws:

IOException - if something fishy happens to the stream.

See Also:

toXML( Writer, String, String )

toXML

public abstract void toXML(Writer stream,
                           String indent,
                           String namespace)
                    throws IOException

Dump the state of the current element as XML output. This function traverses all sibling classes as necessary, and converts the data into pretty-printed XML output. The stream interface should be able to handle large output efficiently, if you use a buffered writer.

Parameters:

stream - is a stream opened and ready for writing. This can also be a string stream for efficient output.

indent - is a String of spaces used for pretty printing. The initial amount of spaces should be an empty string. The parameter is used internally for the recursive traversal. If a null value is specified, no indentation nor linefeeds will be generated.

namespace - is the XML schema namespace prefix. If neither empty nor null, each element will be prefixed with this prefix, and the root element will map the XML namespace. Use null, if you do not need an XML namespace.

Throws:

IOException - if something fishy happens to the stream.

See Also:

BufferedWriter