edu.isi.pegasus.common.util

## Class XMLOutput

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

    public abstract class XMLOutput
    extends java.lang.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$
Author:
  Jens-S. Vöckler

### Constructor Summary

Constructors
Constructor and Description
`XMLOutput()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`static java.lang.String` `escape(java.lang.String original)` Escapes certain characters inappropriate for textual output.
`static java.lang.String` `quote(java.lang.String original, boolean isAttribute)` Escapes certain characters inappropriate for XML content output.
`java.lang.String` `toXML(java.lang.String indent, java.lang.String namespace)` Dumps the state of the current element as XML output.
`void` `toXML(java.io.Writer stream, java.lang.String indent)` Convenience adaptor method invoking the equivalent of:
`abstract void` `toXML(java.io.Writer stream, java.lang.String indent, java.lang.String namespace)` Dump the state of the current element as XML output.
`void` `writeAttribute(java.io.Writer stream, java.lang.String key, java.lang.String value)` XML write helper method writes a quoted attribute onto a stream.
`void` `writeAttribute2(java.io.Writer stream, java.lang.String key, java.lang.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 java.lang.String escape(java.lang.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 java.lang.String quote(java.lang.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(java.io.Writer stream,
                               java.lang.String key,
                               java.lang.String value)
                        throws java.io.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:
  `java.io.IOException` - for stream errors.

#### writeAttribute2

    public void writeAttribute2(java.io.Writer stream,
                                java.lang.String key,
                                java.lang.String value)
                         throws java.io.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:
  `java.io.IOException` - for stream errors.

#### toXML

    public java.lang.String toXML(java.lang.String indent,
                                  java.lang.String namespace)
                           throws java.io.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:
  `java.io.IOException` - when encountering an error constructing the string.

#### toXML

    public void toXML(java.io.Writer stream,
                      java.lang.String indent)
               throws java.io.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:
  `java.io.IOException` - if something fishy happens to the stream.
See Also:
  `toXML( Writer, String, String )`

#### toXML

    public abstract void toXML(java.io.Writer stream,
                               java.lang.String indent,
                               java.lang.String namespace)
                        throws java.io.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:
  `java.io.IOException` - if something fishy happens to the stream.
See Also:
  `BufferedWriter`