Class Formatter

java.lang.Object
org.simpleframework.xml.stream.Formatter

class Formatter extends 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:
  • Nested Class Summary

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

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

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

    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(String plain)
    This is used to buffer characters to the output stream without any translation.
    private void
    data(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(String value)
    This is used to write the specified value to the output with translation to any symbol characters or non text characters.
    void
    This is used to flush the writer when the XML if it has been buffered.
    private boolean
    isEmpty(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 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(String plain)
    This is used to write plain text to the output stream without any translation.
    private void
    write(String plain, String prefix)
    This is used to write plain text to the output stream without any translation.
    void
    writeAttribute(String name, String value, String prefix)
    This is used to write a name value attribute pair.
    void
    This is used to write any comments that have been set.
    void
    writeEnd(String name, String prefix)
    This is used to write an end element tag to the writer.
    void
    writeNamespace(String reference, String prefix)
    This is used to write the namespace to the element.
    void
    This is used to write a prolog to the specified output.
    void
    writeStart(String name, String prefix)
    This method is used to write a start tag for an element.
    void
    This is used to write the specified text value to the writer.
    void
    writeText(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 Details

    • 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 Writer result
      This is the writer that is used to write the XML document.
    • prolog

      private 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 Details

    • Formatter

      public Formatter(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 Details

    • writeProlog

      public void writeProlog() throws 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:
      Exception - thrown if there is an I/O problem
    • writeComment

      public void writeComment(String comment) throws 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:
      Exception
    • writeStart

      public void writeStart(String name, String prefix) throws 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:
      Exception - thrown if there is an I/O exception
    • writeAttribute

      public void writeAttribute(String name, String value, String prefix) throws 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:
      Exception - thrown if there is an I/O exception
    • writeNamespace

      public void writeNamespace(String reference, String prefix) throws 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:
      Exception - thrown if there is an I/O exception
    • writeText

      public void writeText(String text) throws 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:
      Exception - thrown if there is an I/O exception
    • writeText

      public void writeText(String text, Mode mode) throws 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:
      Exception - thrown if there is an I/O exception
    • writeEnd

      public void writeEnd(String name, String prefix) throws 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:
      Exception - thrown if there is an I/O exception
    • write

      private void write(char ch) throws 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:
      Exception
    • write

      private void write(char[] plain) throws 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:
      Exception
    • write

      private void write(String plain) throws 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:
      Exception
    • write

      private void write(String plain, String prefix) throws 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:
      Exception
    • append

      private void append(char ch) throws 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:
      Exception
    • append

      private void append(char[] plain) throws 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:
      Exception
    • append

      private void append(String plain) throws 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:
      Exception
    • data

      private void data(String value) throws 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:
      Exception
    • escape

      private void escape(String value) throws 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:
      Exception
    • escape

      private void escape(char ch) throws 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:
      Exception
    • flush

      public void flush() throws 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:
      Exception
    • unicode

      private 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(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