Package org.simpleframework.xml.stream
Class Formatter
- java.lang.Object
-
- org.simpleframework.xml.stream.Formatter
-
class Formatter extends java.lang.Object
TheFormatter
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.
-
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.
-
-
-
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 theFormatter
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 toformat
- 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 specifiedFormat
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 writtenvalue
- 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 useprefix
- 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 outputprefix
- 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
-
-