Class 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 Description
      XMLOutput()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      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.
      java.lang.String toXML​(java.lang.String indent, java.lang.String namespace)
      Dumps 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