Class AbstractXMLOutputProcessor
- java.lang.Object
-
- org.jdom.output.support.AbstractOutputProcessor
-
- org.jdom.output.support.AbstractXMLOutputProcessor
-
- All Implemented Interfaces:
XMLOutputProcessor
public abstract class AbstractXMLOutputProcessor extends AbstractOutputProcessor implements XMLOutputProcessor
This class provides a concrete implementation ofXMLOutputProcessor
for supporting theXMLOutputter2
.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
andFormatStack
that are managed in theprintElement(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)
andprintContent(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
andEntityRef
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)
ortextRaw(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 thewrite(Writer, char)
orwrite(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
- See Also:
XMLOutputter2
,XMLOutputProcessor
-
-
Constructor Summary
Constructors Constructor Description AbstractXMLOutputProcessor()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected 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
process(Writer out, Format format, List<? extends Content> list)
This will handle printing out a list of nodes.void
process(Writer out, Format format, CDATA cdata)
Print out a
node.CDATA
void
process(Writer out, Format format, Comment comment)
Print out a
.Comment
void
process(Writer out, Format format, DocType doctype)
Print out the
.DocType
void
process(Writer out, Format format, Document doc)
This will print the
to the given Writer.Document
void
process(Writer out, Format format, Element element)
void
process(Writer out, Format format, EntityRef entity)
Print out a
.EntityRef
void
process(Writer out, Format format, ProcessingInstruction pi)
Print out a
.ProcessingInstruction
void
process(Writer out, Format format, Text text)
Print out a
node.Text
protected void
textCDATA(Writer out, String text)
Write aCDATA
to the destinationprotected void
textEntityRef(Writer out, String name)
Write anEntityRef
to the destination.protected void
textRaw(Writer out, char ch)
Convenience method that simply passes the input char towrite(Writer, char)
.protected void
textRaw(Writer out, String str)
Convenience method that simply passes the input str towrite(Writer, String)
.protected void
write(Writer out, char c)
Write a single character to the output Writer.protected void
write(Writer out, String str)
Print some string value to the output.-
Methods inherited from class org.jdom.output.support.AbstractOutputProcessor
buildWalker
-
-
-
-
Field Detail
-
CDATAPRE
protected static final String CDATAPRE
Simple constant for an open-CDATA- See Also:
- Constant Field Values
-
CDATAPOST
protected static final String CDATAPOST
Simple constant for a close-CDATA- See Also:
- Constant Field Values
-
-
Method Detail
-
process
public void process(Writer out, Format format, Document doc) throws IOException
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
public void process(Writer out, Format format, DocType doctype) throws IOException
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
public void process(Writer out, Format format, Element element) throws IOException
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
public void process(Writer out, Format format, List<? extends Content> list) throws IOException
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
public void process(Writer out, Format format, CDATA cdata) throws IOException
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
public void process(Writer out, Format format, Text text) throws IOException
Description copied from interface:XMLOutputProcessor
Print out a
node. Perfoms 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
public void process(Writer out, Format format, Comment comment) throws IOException
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
public void process(Writer out, Format format, ProcessingInstruction pi) throws IOException
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
public void process(Writer out, Format format, EntityRef entity) throws IOException
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
protected void write(Writer out, String str) throws IOException
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
protected void write(Writer out, char c) throws IOException
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
protected void textRaw(Writer out, String str) throws IOException
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
protected void textRaw(Writer out, char ch) throws IOException
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
protected void textEntityRef(Writer out, String name) throws IOException
Write anEntityRef
to the destination.- Parameters:
out
- the destination Writer.name
- the EntityRef's name.- Throws:
IOException
- if the Writer fails.
-
textCDATA
protected void textCDATA(Writer out, String text) throws IOException
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
protected void printDeclaration(Writer out, FormatStack fstack) throws IOException
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
protected void printDocType(Writer out, FormatStack fstack, DocType docType) throws IOException
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
protected void printComment(Writer out, FormatStack fstack, Comment comment) throws IOException
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
protected void printEntityRef(Writer out, FormatStack fstack, EntityRef entity) throws IOException
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
protected void printCDATA(Writer out, FormatStack fstack, CDATA cdata) throws IOException
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
protected void printText(Writer out, FormatStack fstack, Text text) throws IOException
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
protected void printNamespace(Writer out, FormatStack fstack, Namespace ns) throws IOException
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
-
-