Top Description Inners Fields Constructors Methods
org.jdom.output

public Class Format

extends Object
implements Cloneable
Class Inheritance
All Implemented Interfaces
java.lang.Cloneable
Imports
java.lang.reflect.Method, org.jdom.Verifier

Class to encapsulate XMLOutputter format options. Typical users can use the standard format configurations obtained by getRawFormat (no whitespace changes), getPrettyFormat (whitespace beautification), and getCompactFormat (whitespace normalization).

Several modes are available to effect the way textual content is printed. See the documentation for TextMode for details.

Author
Jason Hunter
Version
$Revision: 1.14 $, $Date: 2009/07/23 05:54:23 $

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv class
Format.DefaultEscapeStrategy

Handle common charsets quickly and easily.

public static class
Format.TextMode

Class to signify how text should be handled on output.

Field Summary

Modifier and TypeField and Description
private static final String
pack-priv String
encoding

The encoding format

pack-priv EscapeStrategy
escapeStrategy

entity escape logic

pack-priv boolean
expandEmptyElements

Whether or not to expand empty elements to <tagName></tagName> - default is false

pack-priv boolean
ignoreTrAXEscapingPIs

Whether TrAX output escaping disabling/enabling PIs are ignored or processed - default is false

pack-priv String
indent

The default indent is no spaces (as original document)

pack-priv String
lineSeparator

New line separator

pack-priv Format.TextMode
mode

text handling mode

pack-priv boolean
omitDeclaration

Whether or not to output the XML declaration - default is false

pack-priv boolean
omitEncoding

Whether or not to output the encoding in the XML declaration - default is false

private static final String
STANDARD_ENCODING

standard encoding

private static final String
STANDARD_INDENT

standard value to indent by, if we are indenting

private static final String
STANDARD_LINE_SEPARATOR

standard string with which to end a line

Constructor Summary

AccessConstructor and Description
private
Format()

Creates a new Format instance with default (raw) behavior.

Method Summary

Modifier and TypeMethod and Description
public Object
clone()

Overrides java.lang.Object.clone.

Creates and returns a copy of this object.
public static Format

Returns:

a Format with whitespace normalization
getCompactFormat
()

Returns a new Format object that performs whitespace normalization, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy.

public String

Returns:

the output encoding
getEncoding
()

Returns the configured output encoding.

public EscapeStrategy

Returns:

the current escape strategy
getEscapeStrategy
()

Returns the current escape strategy

public boolean

Returns:

whether empty elements are expanded
getExpandEmptyElements
()

Returns whether empty elements are expanded.

public boolean

Returns:

whether or not TrAX ouput escaping PIs are ignored.
getIgnoreTrAXEscapingPIs
()

Returns whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.

public String

Returns:

the indent string in use
getIndent
()

Returns the indent string in use.

public String

Returns:

the current line separator
getLineSeparator
()

Returns the current line separator.

public boolean

Returns:

whether the XML declaration will be omitted
getOmitDeclaration
()

Returns whether the XML declaration will be omitted.

public boolean

Returns:

whether the XML declaration encoding will be omitted
getOmitEncoding
()

Returns whether the XML declaration encoding will be omitted.

public static Format

Returns:

a Format with whitespace beautification
getPrettyFormat
()

Returns a new Format object that performs whitespace beautification with 2-space indents, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy.

public static Format

Returns:

a Format with no whitespace changes
getRawFormat
()

Returns a new Format object that performs no whitespace changes, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy.

public Format.TextMode

Returns:

the current text output style
getTextMode
()

Returns the current text output style.

public Format

Returns:

a pointer to this Format for chaining
setEncoding
(String
the encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII"
encoding
)

Sets the output encoding.

public Format

Returns:

a pointer to this Format for chaining
setEscapeStrategy
(EscapeStrategy
the EscapeStrategy to use
strategy
)

Sets the EscapeStrategy to use for character escaping.

public Format

Returns:

a pointer to this Format for chaining
setExpandEmptyElements
(boolean
boolean indicating whether or not empty elements should be expanded.
expandEmptyElements
)

This will set whether empty elements are expanded from <tagName/> to <tagName></tagName>.

public void
setIgnoreTrAXEscapingPIs(boolean
boolean indicating whether or not TrAX ouput escaping PIs are ignored.
ignoreTrAXEscapingPIs
)

This will set whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.

public Format

Returns:

a pointer to this Format for chaining
setIndent
(String
String to use for indentation.
indent
)

This will set the indent String to use; this is usually a String of empty spaces.

public Format

Returns:

a pointer to this Format for chaining
setLineSeparator
(String
String line separator to use.
separator
)

This will set the newline separator (lineSeparator).

public Format

Returns:

a pointer to this Format for chaining
setOmitDeclaration
(boolean
boolean indicating whether or not the XML declaration should be omitted.
omitDeclaration
)

This will set whether the XML declaration (<?xml version="1.0"?gt;) will be omitted or not.

public Format

Returns:

a pointer to this Format for chaining
setOmitEncoding
(boolean
boolean indicating whether or not the XML declaration should indicate the document encoding.
omitEncoding
)

This will set whether the XML declaration (<?xml version="1.0" encoding="UTF-8"?>) includes the encoding of the document.

public Format

Returns:

a pointer to this Format for chaining
setTextMode
(Format.TextMode mode)

This sets the text output style.

Inherited from java.lang.Object:
equalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

CVS_IDback to summary
private static final String CVS_ID
encodingback to summary
pack-priv String encoding

The encoding format

escapeStrategyback to summary
pack-priv EscapeStrategy escapeStrategy

entity escape logic

expandEmptyElementsback to summary
pack-priv boolean expandEmptyElements

Whether or not to expand empty elements to <tagName></tagName> - default is false

ignoreTrAXEscapingPIsback to summary
pack-priv boolean ignoreTrAXEscapingPIs

Whether TrAX output escaping disabling/enabling PIs are ignored or processed - default is false

indentback to summary
pack-priv String indent

The default indent is no spaces (as original document)

lineSeparatorback to summary
pack-priv String lineSeparator

New line separator

modeback to summary
pack-priv Format.TextMode mode

text handling mode

omitDeclarationback to summary
pack-priv boolean omitDeclaration

Whether or not to output the XML declaration - default is false

omitEncodingback to summary
pack-priv boolean omitEncoding

Whether or not to output the encoding in the XML declaration - default is false

STANDARD_ENCODINGback to summary
private static final String STANDARD_ENCODING

standard encoding

STANDARD_INDENTback to summary
private static final String STANDARD_INDENT

standard value to indent by, if we are indenting

STANDARD_LINE_SEPARATORback to summary
private static final String STANDARD_LINE_SEPARATOR

standard string with which to end a line

Constructor Detail

Formatback to summary
private Format()

Creates a new Format instance with default (raw) behavior.

Method Detail

cloneback to summary
public Object clone()

Overrides java.lang.Object.clone.

Doc from java.lang.Object.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x
will be true, and that the expression:
x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

Returns:Object

a clone of this instance.

getCompactFormatback to summary
public static Format getCompactFormat()

Returns a new Format object that performs whitespace normalization, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy. Tweaks can be made to the returned Format instance without affecting other instances.

Returns:Format

a Format with whitespace normalization

getEncodingback to summary
public String getEncoding()

Returns the configured output encoding.

Returns:String

the output encoding

getEscapeStrategyback to summary
public EscapeStrategy getEscapeStrategy()

Returns the current escape strategy

Returns:EscapeStrategy

the current escape strategy

getExpandEmptyElementsback to summary
public boolean getExpandEmptyElements()

Returns whether empty elements are expanded.

Returns:boolean

whether empty elements are expanded

getIgnoreTrAXEscapingPIsback to summary
public boolean getIgnoreTrAXEscapingPIs()

Returns whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.

Returns:boolean

whether or not TrAX ouput escaping PIs are ignored.

getIndentback to summary
public String getIndent()

Returns the indent string in use.

Returns:String

the indent string in use

getLineSeparatorback to summary
public String getLineSeparator()

Returns the current line separator.

Returns:String

the current line separator

getOmitDeclarationback to summary
public boolean getOmitDeclaration()

Returns whether the XML declaration will be omitted.

Returns:boolean

whether the XML declaration will be omitted

getOmitEncodingback to summary
public boolean getOmitEncoding()

Returns whether the XML declaration encoding will be omitted.

Returns:boolean

whether the XML declaration encoding will be omitted

getPrettyFormatback to summary
public static Format getPrettyFormat()

Returns a new Format object that performs whitespace beautification with 2-space indents, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy. Tweaks can be made to the returned Format instance without affecting other instances.

Returns:Format

a Format with whitespace beautification

getRawFormatback to summary
public static Format getRawFormat()

Returns a new Format object that performs no whitespace changes, uses the UTF-8 encoding, doesn't expand empty elements, includes the declaration and encoding, and uses the default entity escape strategy. Tweaks can be made to the returned Format instance without affecting other instances.

Returns:Format

a Format with no whitespace changes

getTextModeback to summary
public Format.TextMode getTextMode()

Returns the current text output style.

Returns:Format.TextMode

the current text output style

setEncodingback to summary
public Format setEncoding(String encoding)

Sets the output encoding. The name should be an accepted XML encoding.

Parameters
encoding:String

the encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII"

Returns:Format

a pointer to this Format for chaining

setEscapeStrategyback to summary
public Format setEscapeStrategy(EscapeStrategy strategy)

Sets the EscapeStrategy to use for character escaping.

Parameters
strategy:EscapeStrategy

the EscapeStrategy to use

Returns:Format

a pointer to this Format for chaining

setExpandEmptyElementsback to summary
public Format setExpandEmptyElements(boolean expandEmptyElements)

This will set whether empty elements are expanded from <tagName/> to <tagName></tagName>.

Parameters
expandEmptyElements:boolean

boolean indicating whether or not empty elements should be expanded.

Returns:Format

a pointer to this Format for chaining

setIgnoreTrAXEscapingPIsback to summary
public void setIgnoreTrAXEscapingPIs(boolean ignoreTrAXEscapingPIs)

This will set whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored. Disabling output escaping allows using XML text as element content and outputing it verbatim, i.e. as element children would be.

When processed, these processing instructions are removed from the generated XML text and control whether the element text content is output verbatim or with escaping of the pre-defined entities in XML 1.0. The text to be output verbatim shall be surrounded by the <?javax.xml.transform.disable-output-escaping ?> and <?javax.xml.transform.enable-output-escaping ?> PIs.

When ignored, the processing instructions are present in the generated XML text and the pre-defined entities in XML 1.0 are escaped.

Default: false.

Parameters
ignoreTrAXEscapingPIs:boolean

boolean indicating whether or not TrAX ouput escaping PIs are ignored.

See Also
javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING, javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING
setIndentback to summary
public Format setIndent(String indent)

This will set the indent String to use; this is usually a String of empty spaces. If you pass the empty string (""), then no indentation will happen but newlines will still be generated. Passing null will result in no indentation and no newlines generated. Default: none (null)

Parameters
indent:String

String to use for indentation.

Returns:Format

a pointer to this Format for chaining

setLineSeparatorback to summary
public Format setLineSeparator(String separator)

This will set the newline separator (lineSeparator). The default is \r\n. 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 set TextMode.NORMALIZE, then the newlines will be output verbatim, as "\n" which is how parsers normalize them.

If the format's "indent" property is null (as is the default for the Raw and Compact formats), then this value only effects the newlines written after the declaration and doctype.

Parameters
separator:String

String line separator to use.

Returns:Format

a pointer to this Format for chaining

See Also
setTextMode
setOmitDeclarationback to summary
public Format setOmitDeclaration(boolean omitDeclaration)

This will set whether the XML declaration (<?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.

Parameters
omitDeclaration:boolean

boolean indicating whether or not the XML declaration should be omitted.

Returns:Format

a pointer to this Format for chaining

setOmitEncodingback to summary
public Format setOmitEncoding(boolean omitEncoding)

This will set whether the XML declaration (<?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.

Parameters
omitEncoding:boolean

boolean indicating whether or not the XML declaration should indicate the document encoding.

Returns:Format

a pointer to this Format for chaining

setTextModeback to summary
public Format setTextMode(Format.TextMode mode)

This sets the text output style. Options are available as static TextMode instances. The default is TextMode#PRESERVE.

Returns:Format

a pointer to this Format for chaining

org.jdom.output back to summary

pack-priv Class Format.DefaultEscapeStrategy

extends Object
implements EscapeStrategy
Class Inheritance
All Implemented Interfaces
org.jdom.output.EscapeStrategy

Handle common charsets quickly and easily. Use reflection to query the JDK 1.4 CharsetEncoder class for unknown charsets. If JDK 1.4 isn't around, default to no special encoding.

Field Summary

Modifier and TypeField and Description
private int
pack-priv Method
pack-priv Object

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public boolean
shouldEscape(char ch)

Implements org.jdom.output.EscapeStrategy.shouldEscape.

Test whether the supplied character should be formatted literally or as a character entity.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

bitsback to summary
private int bits
canEncodeback to summary
pack-priv Method canEncode
encoderback to summary
pack-priv Object encoder

Constructor Detail

DefaultEscapeStrategyback to summary
public DefaultEscapeStrategy(String encoding)

Method Detail

shouldEscapeback to summary
public boolean shouldEscape(char ch)

Implements org.jdom.output.EscapeStrategy.shouldEscape.

Doc from org.jdom.output.EscapeStrategy.shouldEscape.

Test whether the supplied character should be formatted literally or as a character entity.

org.jdom.output back to summary

public Class Format.TextMode

extends Object
Class Inheritance

Class to signify how text should be handled on output. The following table provides details.
Text Mode Resulting behavior.
PRESERVE (Default) All content is printed in the format it was created, no whitespace or line separators are are added or removed.
TRIM_FULL_WHITE Content between tags consisting of all whitespace is not printed. If the content contains even one non-whitespace character, it is printed verbatim, whitespace and all.
TRIM Same as TrimAllWhite, plus leading/trailing whitespace are trimmed.
NORMALIZE Same as TextTrim, plus addition interior whitespace is compressed to a single space.
In most cases textual content is aligned with the surrounding tags (after the appropriate text mode is applied). In the case where the only content between the start and end tags is textual, the start tag, text, and end tag are all printed on the same line. If the document being output already has whitespace, it's wise to turn on TRIM mode so the pre-existing whitespace can be trimmed before adding new whitespace.

When a element has a xml:space attribute with the value of "preserve", all formating is turned off and reverts back to the default until the element and its contents have been printed. If a nested element contains another xml:space with the value "default" formatting is turned back on for the child element and then off for the remainder of the parent element.

Field Summary

Modifier and TypeField and Description
private final String
public static final Format.TextMode
NORMALIZE

Mode for text normalization (left and right trim plus internal whitespace is normalized to a single space.

public static final Format.TextMode
PRESERVE

Mode for literal text preservation.

public static final Format.TextMode
TRIM

Mode for text trimming (left and right trim).

public static final Format.TextMode
TRIM_FULL_WHITE

Mode for text trimming of content consisting of nothing but whitespace but otherwise not changing output.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

nameback to summary
private final String name
NORMALIZEback to summary
public static final Format.TextMode NORMALIZE

Mode for text normalization (left and right trim plus internal whitespace is normalized to a single space.

See Also
org.jdom.Element#getTextNormalize
PRESERVEback to summary
public static final Format.TextMode PRESERVE

Mode for literal text preservation.

TRIMback to summary
public static final Format.TextMode TRIM

Mode for text trimming (left and right trim).

TRIM_FULL_WHITEback to summary
public static final Format.TextMode TRIM_FULL_WHITE

Mode for text trimming of content consisting of nothing but whitespace but otherwise not changing output.

Constructor Detail

TextModeback to summary
private TextMode(String name)

Method Detail

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.