Class Formatter


  • class Formatter
    extends java.lang.Object
    The Formatter object is used to format output as XML indented with a configurable indent level. This is used to write start and end tags, as well as attributes and values to the given writer. The output is written directly to the stream with and indentation for each element appropriate to its position in the document hierarchy. If the indent is set to zero then no indent is performed and all XML will appear on the same line.
    See Also:
    Indenter
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Formatter.Tag
      This is used to enumerate the different types of tag that can be written.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static char[] AND
      Represents the XML escape sequence for the ampersand sign.
      private OutputBuffer buffer
      Output buffer used to write the generated XML result to.
      private static char[] CLOSE
      This is used to close a comment section within the document.
      private static char[] DOUBLE
      Represents the XML escape sequence for the double quote.
      private static char[] GREATER
      Represents the XML escape sequence for the greater than sign.
      private Indenter indenter
      Creates the indentations that are used buffer the XML file.
      private Formatter.Tag last
      Represents the last type of content that was written.
      private static char[] LESS
      Represents the XML escape sequence for the less than sign.
      private static char[] NAMESPACE
      Represents the prefix used when declaring an XML namespace.
      private static char[] OPEN
      This is used to open a comment section within the document.
      private java.lang.String prolog
      Represents the prolog to insert at the start of the document.
      private java.io.Writer result
      This is the writer that is used to write the XML document.
      private static char[] SINGLE
      Represents the XML escape sequence for the single quote.
    • Constructor Summary

      Constructors 
      Constructor Description
      Formatter​(java.io.Writer result, Format format)
      Constructor for the Formatter object.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void append​(char ch)
      This is used to buffer a character to the output stream without any translation.
      private void append​(char[] plain)
      This is used to buffer characters to the output stream without any translation.
      private void append​(java.lang.String plain)
      This is used to buffer characters to the output stream without any translation.
      private void data​(java.lang.String value)
      This method is used to write the specified text as a CDATA block within the XML element.
      private void escape​(char ch)
      This is used to write the specified value to the output with translation to any symbol characters or non text characters.
      private void escape​(java.lang.String value)
      This is used to write the specified value to the output with translation to any symbol characters or non text characters.
      void flush()
      This is used to flush the writer when the XML if it has been buffered.
      private boolean isEmpty​(java.lang.String value)
      This method is used to determine if a root annotation value is an empty value.
      private boolean isText​(char ch)
      This is used to determine if the specified character is a text character.
      private char[] symbol​(char ch)
      This is used to convert the specified character to an XML text symbol if the specified character can be converted.
      private java.lang.String unicode​(char ch)
      This is used to convert the the specified character to unicode.
      private void write​(char ch)
      This is used to write a character to the output stream without any translation.
      private void write​(char[] plain)
      This is used to write plain text to the output stream without any translation.
      private void write​(java.lang.String plain)
      This is used to write plain text to the output stream without any translation.
      private void write​(java.lang.String plain, java.lang.String prefix)
      This is used to write plain text to the output stream without any translation.
      void writeAttribute​(java.lang.String name, java.lang.String value, java.lang.String prefix)
      This is used to write a name value attribute pair.
      void writeComment​(java.lang.String comment)
      This is used to write any comments that have been set.
      void writeEnd​(java.lang.String name, java.lang.String prefix)
      This is used to write an end element tag to the writer.
      void writeNamespace​(java.lang.String reference, java.lang.String prefix)
      This is used to write the namespace to the element.
      void writeProlog()
      This is used to write a prolog to the specified output.
      void writeStart​(java.lang.String name, java.lang.String prefix)
      This method is used to write a start tag for an element.
      void writeText​(java.lang.String text)
      This is used to write the specified text value to the writer.
      void writeText​(java.lang.String text, Mode mode)
      This is used to write the specified text value to the writer.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NAMESPACE

        private static final char[] NAMESPACE
        Represents the prefix used when declaring an XML namespace.
      • LESS

        private static final char[] LESS
        Represents the XML escape sequence for the less than sign.
      • GREATER

        private static final char[] GREATER
        Represents the XML escape sequence for the greater than sign.
      • DOUBLE

        private static final char[] DOUBLE
        Represents the XML escape sequence for the double quote.
      • SINGLE

        private static final char[] SINGLE
        Represents the XML escape sequence for the single quote.
      • AND

        private static final char[] AND
        Represents the XML escape sequence for the ampersand sign.
      • OPEN

        private static final char[] OPEN
        This is used to open a comment section within the document.
      • CLOSE

        private static final char[] CLOSE
        This is used to close a comment section within the document.
      • buffer

        private OutputBuffer buffer
        Output buffer used to write the generated XML result to.
      • indenter

        private Indenter indenter
        Creates the indentations that are used buffer the XML file.
      • result

        private java.io.Writer result
        This is the writer that is used to write the XML document.
      • prolog

        private java.lang.String prolog
        Represents the prolog to insert at the start of the document.
      • last

        private Formatter.Tag last
        Represents the last type of content that was written.
    • Constructor Detail

      • Formatter

        public Formatter​(java.io.Writer result,
                         Format format)
        Constructor for the Formatter object. This creates an object that can be used to write XML in an indented format to the specified writer. The XML written will be well formed.
        Parameters:
        result - this is where the XML should be written to
        format - this is the format object to use
    • Method Detail

      • writeProlog

        public void writeProlog()
                         throws java.lang.Exception
        This is used to write a prolog to the specified output. This is only written if the specified Format object has been given a non null prolog. If no prolog is specified then no prolog is written to the generated XML.
        Throws:
        java.lang.Exception - thrown if there is an I/O problem
      • writeComment

        public void writeComment​(java.lang.String comment)
                          throws java.lang.Exception
        This is used to write any comments that have been set. The comment will typically be written at the start of an element to describe the purpose of the element or include debug data that can be used to determine any issues in serialization.
        Parameters:
        comment - this is the comment that is to be written
        Throws:
        java.lang.Exception
      • writeStart

        public void writeStart​(java.lang.String name,
                               java.lang.String prefix)
                        throws java.lang.Exception
        This method is used to write a start tag for an element. If a start tag was written before this then it is closed. Before the start tag is written an indent is generated and placed in front of the tag, this is done for all but the first start tag.
        Parameters:
        name - this is the name of the start tag to be written
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • writeAttribute

        public void writeAttribute​(java.lang.String name,
                                   java.lang.String value,
                                   java.lang.String prefix)
                            throws java.lang.Exception
        This is used to write a name value attribute pair. If the last tag written was not a start tag then this throws an exception. All attribute values written are enclosed in double quotes.
        Parameters:
        name - this is the name of the attribute to be written
        value - this is the value to assigne to the attribute
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • writeNamespace

        public void writeNamespace​(java.lang.String reference,
                                   java.lang.String prefix)
                            throws java.lang.Exception
        This is used to write the namespace to the element. This will write the special attribute using the prefix and reference specified. This will escape the reference if it is required.
        Parameters:
        reference - this is the namespace URI reference to use
        prefix - this is the prefix to used for the namespace
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • writeText

        public void writeText​(java.lang.String text)
                       throws java.lang.Exception
        This is used to write the specified text value to the writer. If the last tag written was a start tag then it is closed. By default this will escape any illegal XML characters.
        Parameters:
        text - this is the text to write to the output
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • writeText

        public void writeText​(java.lang.String text,
                              Mode mode)
                       throws java.lang.Exception
        This is used to write the specified text value to the writer. If the last tag written was a start tag then it is closed. This will use the output mode specified.
        Parameters:
        text - this is the text to write to the output
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • writeEnd

        public void writeEnd​(java.lang.String name,
                             java.lang.String prefix)
                      throws java.lang.Exception
        This is used to write an end element tag to the writer. This will close the element with a short /> if the last tag written was a start tag. However if an end tag or some text was written then a full end tag is written.
        Parameters:
        name - this is the name of the element to be closed
        Throws:
        java.lang.Exception - thrown if there is an I/O exception
      • write

        private void write​(char ch)
                    throws java.lang.Exception
        This is used to write a character to the output stream without any translation. This is used when writing the start tags and end tags, this is also used to write attribute names.
        Parameters:
        ch - this is the character to be written to the output
        Throws:
        java.lang.Exception
      • write

        private void write​(char[] plain)
                    throws java.lang.Exception
        This is used to write plain text to the output stream without any translation. This is used when writing the start tags and end tags, this is also used to write attribute names.
        Parameters:
        plain - this is the text to be written to the output
        Throws:
        java.lang.Exception
      • write

        private void write​(java.lang.String plain)
                    throws java.lang.Exception
        This is used to write plain text to the output stream without any translation. This is used when writing the start tags and end tags, this is also used to write attribute names.
        Parameters:
        plain - this is the text to be written to the output
        Throws:
        java.lang.Exception
      • write

        private void write​(java.lang.String plain,
                           java.lang.String prefix)
                    throws java.lang.Exception
        This is used to write plain text to the output stream without any translation. This is used when writing the start tags and end tags, this is also used to write attribute names.
        Parameters:
        plain - this is the text to be written to the output
        prefix - this is the namespace prefix to be written
        Throws:
        java.lang.Exception
      • append

        private void append​(char ch)
                     throws java.lang.Exception
        This is used to buffer a character to the output stream without any translation. This is used when buffering the start tags so that they can be reset without affecting the resulting document.
        Parameters:
        ch - this is the character to be written to the output
        Throws:
        java.lang.Exception
      • append

        private void append​(char[] plain)
                     throws java.lang.Exception
        This is used to buffer characters to the output stream without any translation. This is used when buffering the start tags so that they can be reset without affecting the resulting document.
        Parameters:
        plain - this is the string that is to be buffered
        Throws:
        java.lang.Exception
      • append

        private void append​(java.lang.String plain)
                     throws java.lang.Exception
        This is used to buffer characters to the output stream without any translation. This is used when buffering the start tags so that they can be reset without affecting the resulting document.
        Parameters:
        plain - this is the string that is to be buffered
        Throws:
        java.lang.Exception
      • data

        private void data​(java.lang.String value)
                   throws java.lang.Exception
        This method is used to write the specified text as a CDATA block within the XML element. This is typically used when the value is large or if it must be preserved in a format that will not be affected by other XML parsers. For large text values this is also faster than performing a character by character escaping.
        Parameters:
        value - this is the text value to be written as CDATA
        Throws:
        java.lang.Exception
      • escape

        private void escape​(java.lang.String value)
                     throws java.lang.Exception
        This is used to write the specified value to the output with translation to any symbol characters or non text characters. This will translate the symbol characters such as "&", ">", "<", and """. This also writes any non text and non symbol characters as integer values like "{".
        Parameters:
        value - the text value to be escaped and written
        Throws:
        java.lang.Exception
      • escape

        private void escape​(char ch)
                     throws java.lang.Exception
        This is used to write the specified value to the output with translation to any symbol characters or non text characters. This will translate the symbol characters such as "&", ">", "<", and """. This also writes any non text and non symbol characters as integer values like "{".
        Parameters:
        ch - the text character to be escaped and written
        Throws:
        java.lang.Exception
      • flush

        public void flush()
                   throws java.lang.Exception
        This is used to flush the writer when the XML if it has been buffered. The flush method is used by the node writer after an end element has been written. Flushing ensures that buffering does not affect the result of the node writer.
        Throws:
        java.lang.Exception
      • unicode

        private java.lang.String unicode​(char ch)
        This is used to convert the the specified character to unicode. This will simply get the decimal representation of the given character as a string so it can be written as an escape.
        Parameters:
        ch - this is the character that is to be converted
        Returns:
        this is the decimal value of the given character
      • isEmpty

        private boolean isEmpty​(java.lang.String value)
        This method is used to determine if a root annotation value is an empty value. Rather than determining if a string is empty be comparing it to an empty string this method allows for the value an empty string represents to be changed in future.
        Parameters:
        value - this is the value to determine if it is empty
        Returns:
        true if the string value specified is an empty value
      • isText

        private boolean isText​(char ch)
        This is used to determine if the specified character is a text character. If the character specified is not a text value then this returns true, otherwise this returns false.
        Parameters:
        ch - this is the character to be evaluated as text
        Returns:
        this returns the true if the character is textual
      • symbol

        private char[] symbol​(char ch)
        This is used to convert the specified character to an XML text symbol if the specified character can be converted. If the character cannot be converted to a symbol null is returned.
        Parameters:
        ch - this is the character that is to be converted
        Returns:
        this is the symbol character that has been resolved