|
JDOM 1.0beta10 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.jdom.output.XMLOutputter
Outputs a JDOM document as a stream of bytes. The outputter can manage many
styles of document formatting, from untouched to pretty printed. The default
is to output the document content exactly as created, but this can be changed
by setting a new Format object. For pretty-print output, use
. For whitespace-normalized
output, use Format.getPrettyFormat()
.
Format.getCompactFormat()
There are
methods to print any of
the standard JDOM classes, including Document and Element, to either a Writer
or an OutputStream. Warning: When outputting to a Writer, make sure
the writer's encoding matches the encoding setting in the Format object. This
ensures the encoding in which the content is written (controlled by the
Writer configuration) matches the encoding placed in the document's XML
declaration (controlled by the XMLOutputter). Because a Writer cannot be
queried for its encoding, the information must be passed to the Format
manually in its constructor or via the
output(...)
method. The default encoding is
UTF-8.
Format.setEncoding(java.lang.String)
The methods
are for
convenience only; for top performance you should call one of the outputString(...)
methods and pass in your own Writer or
OutputStream if possible.
output(...)
XML declarations are always printed on their own line followed by a line
seperator (this doesn't change the semantics of the document). To omit
printing of the declaration use
. To omit printing of the
encoding in the declaration use Format.setOmitDeclaration(boolean)
.
Unfortunatly there is currently no way to know the original encoding of the
document.
Format.setOmitEncoding(boolean)
Empty elements are by default printed as <empty/>, but this can be
configured with
to cause
them to be expanded to <empty></empty>.
Format.setExpandEmptyElements(boolean)
Nested Class Summary | |
protected class |
XMLOutputter.NamespaceStack
Our own null subclass of NamespaceStack. |
Field Summary | |
protected Format |
currentFormat
|
protected Format |
preserveFormat
|
protected Format |
userFormat
|
Constructor Summary | |
XMLOutputter()
This will create an XMLOutputter with the default
Format matching Format.getRawFormat() . |
|
XMLOutputter(Format format)
This will create an XMLOutputter with the specified
format characteristics. |
|
XMLOutputter(java.lang.String indent)
Deprecated. Deprecated in Beta 10, use the Format class instead |
|
XMLOutputter(java.lang.String indent,
boolean newlines)
Deprecated. Deprecated in Beta 10, use the Format class instead |
|
XMLOutputter(java.lang.String indent,
boolean newlines,
java.lang.String encoding)
Deprecated. Deprecated in Beta 10, use the Format class instead |
|
XMLOutputter(XMLOutputter that)
This will create an XMLOutputter with all the
options as set in the given XMLOutputter . |
Method Summary | |
java.lang.Object |
clone()
Returns a copy of this XMLOutputter. |
java.lang.String |
escapeAttributeEntities(java.lang.String str)
This will take the pre-defined entities in XML 1.0 and convert their character representation to the appropriate entity reference, suitable for XML attributes. |
java.lang.String |
escapeElementEntities(java.lang.String str)
This will take the three pre-defined entities in XML 1.0 (used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content. |
Format |
getFormat()
Returns the current format object in use by the outputter. |
void |
output(CDATA cdata,
java.io.OutputStream out)
Print out a node. |
void |
output(CDATA cdata,
java.io.Writer out)
Print out a node. |
void |
output(Comment comment,
java.io.OutputStream out)
Print out a . |
void |
output(Comment comment,
java.io.Writer out)
Print out a . |
void |
output(DocType doctype,
java.io.OutputStream out)
Print out the . |
void |
output(DocType doctype,
java.io.Writer out)
Print out the . |
void |
output(Document doc,
java.io.OutputStream out)
This will print the Document to the given output stream. |
void |
output(Document doc,
java.io.Writer out)
This will print the Document to the given Writer. |
void |
output(Element element,
java.io.OutputStream out)
Print out an , including
its s, and all
contained (child) elements, etc. |
void |
output(Element element,
java.io.Writer out)
Print out an , including
its s, and all
contained (child) elements, etc. |
void |
output(EntityRef entity,
java.io.OutputStream out)
Print out a . |
void |
output(EntityRef entity,
java.io.Writer out)
Print out a . |
void |
output(java.util.List list,
java.io.OutputStream out)
This will handle printing out a list of nodes. |
void |
output(java.util.List list,
java.io.Writer out)
This will handle printing out a list of nodes. |
void |
output(ProcessingInstruction pi,
java.io.OutputStream out)
Print out a . |
void |
output(ProcessingInstruction pi,
java.io.Writer out)
Print out a . |
void |
output(Text text,
java.io.OutputStream out)
Print out a node. |
void |
output(Text text,
java.io.Writer out)
Print out a node. |
void |
outputElementContent(Element element,
java.io.OutputStream out)
This will handle printing out an 's content only, not including its tag, and
attributes. |
void |
outputElementContent(Element element,
java.io.Writer out)
This will handle printing out an 's content only, not including its tag, and
attributes. |
java.lang.String |
outputString(CDATA cdata)
Return a string representing a CDATA node. |
java.lang.String |
outputString(Comment comment)
Return a string representing a comment. |
java.lang.String |
outputString(DocType doctype)
Return a string representing a DocType. |
java.lang.String |
outputString(Document doc)
Return a string representing a document. |
java.lang.String |
outputString(Element element)
Return a string representing an element. |
java.lang.String |
outputString(EntityRef entity)
Return a string representing an entity. |
java.lang.String |
outputString(java.util.List list)
Return a string representing a list of nodes. |
java.lang.String |
outputString(ProcessingInstruction pi)
Return a string representing a PI. |
java.lang.String |
outputString(Text text)
Return a string representing a Text node. |
protected void |
printAttributes(java.io.Writer out,
java.util.List attributes,
Element parent,
XMLOutputter.NamespaceStack namespaces)
This will handle printing of a list. |
protected void |
printCDATA(java.io.Writer out,
CDATA cdata)
This will handle printing of text. |
protected void |
printComment(java.io.Writer out,
Comment comment)
This will handle printing of comments. |
protected void |
printContentRange(java.io.Writer out,
java.util.List content,
int start,
int end,
int level,
XMLOutputter.NamespaceStack namespaces)
This will handle printing of content within a given range. |
protected void |
printDeclaration(java.io.Writer out,
Document doc,
java.lang.String encoding)
This will handle printing of the declaration. |
protected void |
printDocType(java.io.Writer out,
DocType docType)
This handle printing the DOCTYPE declaration if one exists. |
protected void |
printElement(java.io.Writer out,
Element element,
int level,
XMLOutputter.NamespaceStack namespaces)
This will handle printing of a ,
its s, and all contained (child)
elements, etc. |
protected void |
printEntityRef(java.io.Writer out,
EntityRef entity)
This will handle printing a . |
protected void |
printProcessingInstruction(java.io.Writer out,
ProcessingInstruction pi)
This will handle printing of processing instructions. |
protected void |
printString(java.io.Writer out,
java.lang.String str)
This will handle printing a string. |
protected void |
printText(java.io.Writer out,
Text text)
This will handle printing of strings. |
protected void |
printTextRange(java.io.Writer out,
java.util.List content,
int start,
int end)
This will handle printing of a sequence of
or nodes. |
void |
setEncoding(java.lang.String encoding)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setExpandEmptyElements(boolean expandEmptyElements)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setFormat(Format newFormat)
Sets the new format logic for the outputter. |
void |
setIndent(java.lang.String indent)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setLineSeparator(java.lang.String separator)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setNewlines(boolean newlines)
Deprecated. Deprecated in Beta 10 since newlines will now just be added if indent is non-null |
void |
setOmitDeclaration(boolean omitDeclaration)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setOmitEncoding(boolean omitEncoding)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setTextNormalize(boolean textNormalize)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setTextTrim(boolean textTrim)
Deprecated. Deprecated in Beta 10, use the Format class instead |
void |
setTrimAllWhite(boolean trimAllWhite)
Deprecated. Deprecated in Beta 10, use the Format class instead |
java.lang.String |
toString()
Return a string listing of the settings for this XMLOutputter instance. |
Methods inherited from class java.lang.Object |
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
protected Format userFormat
protected Format preserveFormat
protected Format currentFormat
Constructor Detail |
public XMLOutputter()
XMLOutputter
with the default
Format
matching Format.getRawFormat()
.
public XMLOutputter(Format format)
XMLOutputter
with the specified
format characteristics.
public XMLOutputter(java.lang.String indent)
XMLOutputter
with the given indent
added but no new lines added; all whitespace from the element text
content is included as well.
indent
- the indent string, usually some number of spacespublic XMLOutputter(java.lang.String indent, boolean newlines)
XMLOutputter
with the given indent
that prints newlines only if newlines
is
true
; all whitespace from the element text content is
included as well.
indent
- the indent String
, usually some number
of spacesnewlines
- true
indicates new lines should be
printed, else new lines are ignored (compacted).public XMLOutputter(java.lang.String indent, boolean newlines, java.lang.String encoding)
XMLOutputter
with
the given indent and new lines printing only if
newlines
is true
, and encoding format
encoding
.
indent
- the indent String
, usually some number
of spacesnewlines
- true
indicates new lines should be
printed, else new lines are ignored (compacted).encoding
- set encoding format. Use XML-style names like
"UTF-8" or "ISO-8859-1" or "US-ASCII"public XMLOutputter(XMLOutputter that)
XMLOutputter
with all the
options as set in the given XMLOutputter
. Note
that XMLOutputter two = (XMLOutputter)one.clone();
would work equally well.
that
- the XMLOutputter to cloneMethod Detail |
public void setFormat(Format newFormat)
newFormat
- the format to use for outputpublic Format getFormat()
public void setLineSeparator(java.lang.String separator)
lineSeparator
).
The default is \r\n
. Note that if the "newlines"
property is false, this value is irrelevant. To make it output
the system default line ending string, call
setLineSeparator(System.getProperty("line.separator"))
To output "UNIX-style" documents, call
setLineSeparator("\n")
. To output "Mac-style"
documents, call setLineSeparator("\r")
. DOS-style
documents use CR-LF ("\r\n"), which is the default.
Note that this only applies to newlines generated by the
outputter. If you parse an XML document that contains newlines
embedded inside a text node, and you do not call
setTextNormalize
, then the newlines will be output
verbatim, as "\n" which is how parsers normalize them.
separator
- String
line separator to use.setNewlines(boolean)
,
setTextNormalize(boolean)
public void setNewlines(boolean newlines)
lineSeparator
) should
be added during output as an attempt to beautify code without
pre-existing whitespace. Usually called in conjunction with setIndent(java.lang.String)
.
newlines
- true
indicates new lines should be
added for beautification.setLineSeparator(String)
public void setEncoding(java.lang.String encoding)
encoding
- the encoding format. Use XML-style names like
"UTF-8" or "ISO-8859-1" or "US-ASCII"public void setOmitEncoding(boolean omitEncoding)
<?xml version="1.0"
encoding="UTF-8"?>
)
includes the encoding of the document. It is common to omit
this in uses such as WML and other wireless device protocols.
omitEncoding
- boolean
indicating whether or not
the XML declaration should indicate the document encoding.public void setOmitDeclaration(boolean omitDeclaration)
<?xml version="1.0"?gt;
)
will be omitted or not. It is common to omit this in uses such
as SOAP and XML-RPC calls.
omitDeclaration
- boolean
indicating whether or not
the XML declaration should be omitted.public void setExpandEmptyElements(boolean expandEmptyElements)
<tagName/>
to
<tagName></tagName>
.
expandEmptyElements
- boolean
indicating whether or not
empty elements should be expanded.public void setTrimAllWhite(boolean trimAllWhite)
Default: false
trimAllWhite
- boolean
true=>content consisting of
only whitespace is not print, false=>use text verbatimpublic void setTextTrim(boolean textTrim)
Default: false
textTrim
- boolean
true=>trim the leading/trailing
whitespace, false=>use text verbatimpublic void setTextNormalize(boolean textNormalize)
Element.getTextNormalize()
.
Default: false
textNormalize
- boolean
true=>normalize the
whitespace, false=>use text verbatimpublic void setIndent(java.lang.String indent)
String
to use; this
is usually a String
of empty spaces. If you pass
null, or the empty string (""), then no indentation will
happen. Default: none (null)
indent
- String
to use for indentation.public void output(Document doc, java.io.OutputStream out) throws java.io.IOException
Document
to the given output stream.
The characters are printed using the encoding specified in the
constructor, or a default of UTF-8.
doc
- Document
to format.out
- OutputStream
to use.
java.io.IOException
- - if there's any problem writing.public void output(DocType doctype, java.io.OutputStream out) throws java.io.IOException
DocType
.
doctype
- DocType
to output.out
- OutputStream
to use.
java.io.IOException
public void output(Element element, java.io.OutputStream out) throws java.io.IOException
Element
, including
its Attribute
s, and all
contained (child) elements, etc.
element
- Element
to output.out
- Writer
to use.
java.io.IOException
public void outputElementContent(Element element, java.io.OutputStream out) throws java.io.IOException
Element
's content only, not including its tag, and
attributes. This can be useful for printing the content of an
element that contains HTML, like "<description>JDOM is
<b>fun>!</description>".
element
- Element
to output.out
- OutputStream
to use.
java.io.IOException
public void output(java.util.List list, java.io.OutputStream out) throws java.io.IOException
list
- List
of nodes.out
- OutputStream
to use.
java.io.IOException
public void output(CDATA cdata, java.io.OutputStream out) throws java.io.IOException
CDATA
node.
cdata
- CDATA
to output.out
- OutputStream
to use.
java.io.IOException
public void output(Text text, java.io.OutputStream out) throws java.io.IOException
Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
text
- Text
to output.out
- OutputStream
to use.
java.io.IOException
public void output(Comment comment, java.io.OutputStream out) throws java.io.IOException
Comment
.
comment
- Comment
to output.out
- OutputStream
to use.
java.io.IOException
public void output(ProcessingInstruction pi, java.io.OutputStream out) throws java.io.IOException
ProcessingInstruction
.
pi
- ProcessingInstruction
to output.out
- OutputStream
to use.
java.io.IOException
public void output(EntityRef entity, java.io.OutputStream out) throws java.io.IOException
EntityRef
.
entity
- EntityRef
to output.out
- OutputStream
to use.
java.io.IOException
public void output(Document doc, java.io.Writer out) throws java.io.IOException
Document
to the given Writer.
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.
doc
- Document
to format.out
- Writer
to use.
java.io.IOException
- - if there's any problem writing.public void output(DocType doctype, java.io.Writer out) throws java.io.IOException
DocType
.
doctype
- DocType
to output.out
- Writer
to use.
java.io.IOException
public void output(Element element, java.io.Writer out) throws java.io.IOException
Element
, including
its Attribute
s, and all
contained (child) elements, etc.
element
- Element
to output.out
- Writer
to use.
java.io.IOException
public void outputElementContent(Element element, java.io.Writer out) throws java.io.IOException
Element
's content only, not including its tag, and
attributes. This can be useful for printing the content of an
element that contains HTML, like "<description>JDOM is
<b>fun>!</description>".
element
- Element
to output.out
- Writer
to use.
java.io.IOException
public void output(java.util.List list, java.io.Writer out) throws java.io.IOException
list
- List
of nodes.out
- Writer
to use.
java.io.IOException
public void output(CDATA cdata, java.io.Writer out) throws java.io.IOException
CDATA
node.
cdata
- CDATA
to output.out
- Writer
to use.
java.io.IOException
public void output(Text text, java.io.Writer out) throws java.io.IOException
Text
node. Perfoms
the necessary entity escaping and whitespace stripping.
text
- Text
to output.out
- Writer
to use.
java.io.IOException
public void output(Comment comment, java.io.Writer out) throws java.io.IOException
Comment
.
comment
- Comment
to output.out
- Writer
to use.
java.io.IOException
public void output(ProcessingInstruction pi, java.io.Writer out) throws java.io.IOException
ProcessingInstruction
.
pi
- ProcessingInstruction
to output.out
- Writer
to use.
java.io.IOException
public void output(EntityRef entity, java.io.Writer out) throws java.io.IOException
EntityRef
.
entity
- EntityRef
to output.out
- Writer
to use.
java.io.IOException
public java.lang.String outputString(Document doc)
doc
- Document
to format.public java.lang.String outputString(DocType doctype)
doctype
- DocType
to format.public java.lang.String outputString(Element element)
element
- Element
to format.public java.lang.String outputString(java.util.List list)
list
- List
to format.public java.lang.String outputString(CDATA cdata)
cdata
- CDATA
to format.public java.lang.String outputString(Text text)
text
- Text
to format.public java.lang.String outputString(Comment comment)
comment
- Comment
to format.public java.lang.String outputString(ProcessingInstruction pi)
pi
- ProcessingInstruction
to format.public java.lang.String outputString(EntityRef entity)
entity
- EntityRef
to format.protected void printDeclaration(java.io.Writer out, Document doc, java.lang.String encoding) throws java.io.IOException
doc
- Document
whose declaration to write.out
- Writer
to use.encoding
- The encoding to add to the declaration
java.io.IOException
protected void printDocType(java.io.Writer out, DocType docType) throws java.io.IOException
docType
- Document
whose declaration to write.out
- Writer
to use.
java.io.IOException
protected void printComment(java.io.Writer out, Comment comment) throws java.io.IOException
comment
- Comment
to write.out
- Writer
to use.
java.io.IOException
protected void printProcessingInstruction(java.io.Writer out, ProcessingInstruction pi) throws java.io.IOException
pi
- ProcessingInstruction
to write.out
- Writer
to use.
java.io.IOException
protected void printEntityRef(java.io.Writer out, EntityRef entity) throws java.io.IOException
EntityRef
.
Only the entity reference such as &entity;
will be printed. However, subclasses are free to override
this method to print the contents of the entity instead.
entity
- EntityRef
to output.out
- Writer
to use.
java.io.IOException
protected void printCDATA(java.io.Writer out, CDATA cdata) throws java.io.IOException
CDATA
text.
cdata
- CDATA
to output.out
- Writer
to use.
java.io.IOException
protected void printText(java.io.Writer out, Text text) throws java.io.IOException
Text
strings.
text
- Text
to write.out
- Writer
to use.
java.io.IOException
protected void printString(java.io.Writer out, java.lang.String str) throws java.io.IOException
java.io.IOException
protected void printElement(java.io.Writer out, Element element, int level, XMLOutputter.NamespaceStack namespaces) throws java.io.IOException
Element
,
its Attribute
s, and all contained (child)
elements, etc.
element
- Element
to output.out
- Writer
to use.level
- int
level of indention.namespaces
- List
stack of Namespaces in scope.
java.io.IOException
protected void printContentRange(java.io.Writer out, java.util.List content, int start, int end, int level, XMLOutputter.NamespaceStack namespaces) throws java.io.IOException
content
- List
of content to outputstart
- index of first content node (inclusive.end
- index of last content node (exclusive).out
- Writer
to use.level
- int
level of indentation.namespaces
- List
stack of Namespaces in scope.
java.io.IOException
protected void printTextRange(java.io.Writer out, java.util.List content, int start, int end) throws java.io.IOException
CDATA
or Text
nodes. It is a error to have any other
pass this method any other type of node.
content
- List
of content to outputstart
- index of first content node (inclusive).end
- index of last content node (exclusive).out
- Writer
to use.
java.io.IOException
protected void printAttributes(java.io.Writer out, java.util.List attributes, Element parent, XMLOutputter.NamespaceStack namespaces) throws java.io.IOException
Attribute
list.
attributes
- List
of Attribute objctsout
- Writer
to use
java.io.IOException
public java.lang.String escapeAttributeEntities(java.lang.String str)
str
- String
input to escape.
String
with escaped content.public java.lang.String escapeElementEntities(java.lang.String str)
str
- String
input to escape.
String
with escaped content.public java.lang.Object clone()
public java.lang.String toString()
|
JDOM 1.0beta10 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |