Class AbstractXMLOutputProcessor
- All Implemented Interfaces:
XMLOutputProcessor
XMLOutputProcessor
for supporting the XMLOutputter
.
Overview
This class is marked abstract even though all methods are fully implemented.
The process*(...)
methods are public because they match the
XMLOutputProcessor interface but the remaining methods are all protected.
People who want to create a custom XMLOutputProcessor for XMLOutputter are
able to extend this class and modify any functionality they want. Before
sub-classing this you should first check to see if the Format
class
can get you the results you want.
Subclasses of this should have reentrant methods. This is easiest to accomplish simply by not allowing any instance fields. If your sub-class has an instance field/variable, then it's probably broken.
The Stacks
One significant feature of this implementation is that it creates and
maintains both a NamespaceStack
and FormatStack
that are
managed in the
printElement(Writer, FormatStack, NamespaceStack, Element)
method.
The stacks are pushed and popped in that method only. They significantly
improve the performance and readability of the code.
The NamespaceStack is only sent through to the
printElement(Writer, FormatStack, NamespaceStack, Element)
and
printContent(Writer, FormatStack, NamespaceStack, Walker)
methods,
but the FormatStack is pushed through to all print* Methods.
Text Processing
In XML the concept of 'Text' can be loosely defined as anything that can be
found between an Element's start and end tags, excluding Comments and
Processing Instructions. When considered from a JDOM perspective, this means
Text
, CDATA
and EntityRef
content. This will be
referred to as 'Text-like content'
XMLOutputter delegates the management and formatting of Content to a
Walker instance. See Walker
and its various implementations for
details on how the Element content is processed.
Because the Walker interface specifies that Text/CDATA content may be
returned as either Text/CDATA instances or as formatted String values
this class sometimes uses printCDATA(...) and printText(...), and sometimes
uses the more direct textCDATA(Writer, String)
or
textRaw(Writer, String)
as
appropriate. In other words, subclasses should probably override these second
methods instead of the print methods.
Non-Text Content
Non-text content is processed via the respective print* methods. The usage should be logical based on the method name.
The general observations are:
- printElement - maintains the Stacks, prints the element open tags, with attributes and namespaces. It checks to see whether the Element is text-only, or has non-text content. If it is text-only there is no indent/newline handling and it delegates to the correct text-type print method, otherwise it delegates to printContent.
- printContent is called to output all lists of Content. It assumes that all whitespace indentation/newlines are appropriate before it is called, but it will ensure that padding is appropriate between the items in the list.
Final Notes
No methods actually write to the destination Writer except thewrite(...)
methods. Thus, all other methods do their
respective processing and delegate the actual destination output to the
write(Writer, char)
or write(Writer, String)
methods.
All Text-like content (printCDATA, printText, and printEntityRef) will ultimately be output through the the text* methods (and no other content).
- Since:
- JDOM2
- Author:
- Rolf Lear
- See Also:
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected void
attributeEscapedEntitiesFilter
(Writer out, FormatStack fstack, String value) This will take the three pre-defined entities in XML 1.0 ('<', '>', and '&' - used specifically in XML elements) as well as CR/NL and Quote characters which require escaping inside Attribute values and convert their character representation to the appropriate entity reference suitable for XML attribute content.protected void
printAttribute
(Writer out, FormatStack fstack, Attribute attribute) This will handle printing of an
.Attribute
protected void
printCDATA
(Writer out, FormatStack fstack, CDATA cdata) This will handle printing of aCDATA
.protected void
printComment
(Writer out, FormatStack fstack, Comment comment) This will handle printing of aComment
.protected void
printContent
(Writer out, FormatStack fstack, NamespaceStack nstack, Walker walker) This will handle printing of a List ofContent
.protected void
printDeclaration
(Writer out, FormatStack fstack) This will handle printing of the XML declaration.protected void
printDocType
(Writer out, FormatStack fstack, DocType docType) This will handle printing of aDocType
.protected void
printDocument
(Writer out, FormatStack fstack, NamespaceStack nstack, Document doc) This will handle printing of aDocument
.protected void
printElement
(Writer out, FormatStack fstack, NamespaceStack nstack, Element element) This will handle printing of anElement
.protected void
printEntityRef
(Writer out, FormatStack fstack, EntityRef entity) This will handle printing of anEntityRef
.protected void
printNamespace
(Writer out, FormatStack fstack, Namespace ns) This will handle printing of any needed
declarations.Namespace
protected void
printProcessingInstruction
(Writer out, FormatStack fstack, ProcessingInstruction pi) This will handle printing of aProcessingInstruction
.protected void
printText
(Writer out, FormatStack fstack, Text text) This will handle printing of aText
.void
This will handle printing out a list of nodes.void
Print out a
node.CDATA
void
Print out a
.Comment
void
Print out the
.DocType
void
This will print the
to the given Writer.Document
void
void
Print out a
.EntityRef
void
process
(Writer out, Format format, ProcessingInstruction pi) Print out a
.ProcessingInstruction
void
Print out a
node.Text
protected void
Write aCDATA
to the destinationprotected void
textEntityRef
(Writer out, String name) Write anEntityRef
to the destination.protected void
Convenience method that simply passes the input char towrite(Writer, char)
.protected void
Convenience method that simply passes the input str towrite(Writer, String)
.protected void
Write a single character to the output Writer.protected void
Print some string value to the output.Methods inherited from class org.jdom2.output.support.AbstractOutputProcessor
buildWalker
-
Field Details
-
CDATAPRE
Simple constant for an open-CDATA- See Also:
-
CDATAPOST
Simple constant for a close-CDATA- See Also:
-
-
Constructor Details
-
AbstractXMLOutputProcessor
public AbstractXMLOutputProcessor()
-
-
Method Details
-
process
Description copied from interface:XMLOutputProcessor
This will print the
to the given Writer.Document
Warning: using your own Writer may cause the outputter's preferred character encoding to be ignored. If you use encodings other than UTF-8, we recommend using the method that takes an OutputStream instead.
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output styledoc
-Document
to format.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out the
.DocType
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output styledoctype
-DocType
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output styleelement
-Element
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output stylelist
-List
of nodes.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out a
node.CDATA
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output stylecdata
-CDATA
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out a
node. Performs the necessary entity escaping and whitespace stripping.Text
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output styletext
-Text
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out a
.Comment
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output stylecomment
-Comment
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out a
.ProcessingInstruction
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output stylepi
-ProcessingInstruction
to output.- Throws:
IOException
- if there's any problem writing.
-
process
Description copied from interface:XMLOutputProcessor
Print out a
.EntityRef
- Specified by:
process
in interfaceXMLOutputProcessor
- Parameters:
out
-Writer
to use.format
-Format
instance specifying output styleentity
-EntityRef
to output.- Throws:
IOException
- if there's any problem writing.
-
write
Print some string value to the output. Null values are ignored. This ignore-null property is used for a few tricks.- Parameters:
out
- The Writer to write to.str
- The String to write (can be null).- Throws:
IOException
- if the out Writer fails.
-
write
Write a single character to the output Writer.- Parameters:
out
- The Writer to write to.c
- The char to write.- Throws:
IOException
- if the Writer fails.
-
attributeEscapedEntitiesFilter
protected void attributeEscapedEntitiesFilter(Writer out, FormatStack fstack, String value) throws IOException This will take the three pre-defined entities in XML 1.0 ('<', '>', and '&' - used specifically in XML elements) as well as CR/NL and Quote characters which require escaping inside Attribute values and convert their character representation to the appropriate entity reference suitable for XML attribute content. Further, some special characters (e.g. characters that are not valid in the current encoding) are converted to escaped representations.Note: If
FormatStack.getEscapeOutput()
is false then no escaping will happen.- Parameters:
out
- The destination Writerfstack
- TheFormatStack
value
-String
Attribute value to escape.- Throws:
IOException
- if the destination Writer fails.IllegalDataException
- if an entity can not be escaped
-
textRaw
Convenience method that simply passes the input str towrite(Writer, String)
. This could be useful for subclasses to hook in to. All text-type output will come through this or thetextRaw(Writer, char)
method.- Parameters:
out
- the destination writer.str
- the String to write.- Throws:
IOException
- if the Writer fails.
-
textRaw
Convenience method that simply passes the input char towrite(Writer, char)
. This could be useful for subclasses to hook in to. All text-type output will come through this or thetextRaw(Writer, String)
method.- Parameters:
out
- the destination Writer.ch
- the char to write.- Throws:
IOException
- if the Writer fails.
-
textEntityRef
Write anEntityRef
to the destination.- Parameters:
out
- the destination Writer.name
- the EntityRef's name.- Throws:
IOException
- if the Writer fails.
-
textCDATA
Write aCDATA
to the destination- Parameters:
out
- the destination Writertext
- the CDATA text- Throws:
IOException
- if the Writer fails.
-
printDocument
protected void printDocument(Writer out, FormatStack fstack, NamespaceStack nstack, Document doc) throws IOException This will handle printing of aDocument
.- Parameters:
out
-Writer
to use.fstack
- the FormatStacknstack
- the NamespaceStackdoc
-Document
to write.- Throws:
IOException
- if the destination Writer fails
-
printDeclaration
This will handle printing of the XML declaration. Assumes XML version 1.0 since we don't directly know.- Parameters:
out
-Writer
to use.fstack
- the FormatStack- Throws:
IOException
- if the destination Writer fails
-
printDocType
This will handle printing of aDocType
.- Parameters:
out
-Writer
to use.fstack
- the FormatStackdocType
-DocType
to write.- Throws:
IOException
- if the destination Writer fails
-
printProcessingInstruction
protected void printProcessingInstruction(Writer out, FormatStack fstack, ProcessingInstruction pi) throws IOException This will handle printing of aProcessingInstruction
.- Parameters:
out
-Writer
to use.fstack
- the FormatStackpi
-ProcessingInstruction
to write.- Throws:
IOException
- if the destination Writer fails
-
printComment
This will handle printing of aComment
.- Parameters:
out
-Writer
to use.fstack
- the FormatStackcomment
-Comment
to write.- Throws:
IOException
- if the destination Writer fails
-
printEntityRef
This will handle printing of anEntityRef
.- Parameters:
out
-Writer
to use.fstack
- the FormatStackentity
-EntotyRef
to write.- Throws:
IOException
- if the destination Writer fails
-
printCDATA
This will handle printing of aCDATA
.- Parameters:
out
-Writer
to use.fstack
- the FormatStackcdata
-CDATA
to write.- Throws:
IOException
- if the destination Writer fails
-
printText
This will handle printing of aText
.- Parameters:
out
-Writer
to use.fstack
- the FormatStacktext
-Text
to write.- Throws:
IOException
- if the destination Writer fails
-
printElement
protected void printElement(Writer out, FormatStack fstack, NamespaceStack nstack, Element element) throws IOException This will handle printing of anElement
.This method arranges for outputting the Element infrastructure including Namespace Declarations and Attributes.
- Parameters:
out
-Writer
to use.fstack
- the FormatStacknstack
- the NamespaceStackelement
-Element
to write.- Throws:
IOException
- if the destination Writer fails
-
printContent
protected void printContent(Writer out, FormatStack fstack, NamespaceStack nstack, Walker walker) throws IOException This will handle printing of a List ofContent
.The list of Content is basically processed as one of three types of content
- Consecutive text-type (Text, CDATA, and EntityRef) content
- Stand-alone text-type content
- Non-text-type content.
- identify one of the three types (consecutive, stand-alone, non-text)
- do indent if any is specified.
- send the type to the respective print* handler (e.g.
printCDATA(Writer, FormatStack, CDATA)
, orprintComment(Writer, FormatStack, Comment)
, - do a newline if one is specified.
- loop back to 1. until there's no more content to process.
- Parameters:
out
-Writer
to use.fstack
- the FormatStacknstack
- the NamespaceStackwalker
-Walker
ofContent
to write.- Throws:
IOException
- if the destination Writer fails
-
printNamespace
This will handle printing of any needed
declarations.Namespace
- Parameters:
out
-Writer
to use.fstack
- The current FormatStackns
-Namespace
to print definition of- Throws:
IOException
- if the output fails
-
printAttribute
protected void printAttribute(Writer out, FormatStack fstack, Attribute attribute) throws IOException This will handle printing of an
.Attribute
- Parameters:
out
-Writer
to use.fstack
- The current FormatStackattribute
-Attribute
to output- Throws:
IOException
- if the output fails
-