JDOM
2.0.5

org.jdom2.output
Class Format

java.lang.Object
  extended by org.jdom2.output.Format
All Implemented Interfaces:
java.lang.Cloneable

public class Format
extends java.lang.Object
implements java.lang.Cloneable

Class to encapsulate XMLOutputter format options. Typically users adapt 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 Format.TextMode for details.

Note about Line Separator:

By default JDOM will always use the CRNL sequence "\r\n" for output. This can be changed in a number of different ways. See the LineSeparator enumeration for more information.

Note about XML Character Escaping:

JDOM will escape characters in the output based on the EscapeStrategy that is specified by this Format. The Format will by default use a sensible EscapeStrategy that is based on the character encoding of the output. If the default escape mechanism is not producing the correct results you can change the EscapeStrategy on the format to suit your own needs.

Author:
Jason Hunter, Rolf Lear
See Also:
LineSeparator

Nested Class Summary
static class Format.TextMode
          Class to signify how text should be handled on output.
 
Method Summary
 Format clone()
           
static java.lang.String compact(java.lang.String str)
          Use the XML Specification definition of whitespace to compact the input value.
static java.lang.String escapeAttribute(EscapeStrategy strategy, java.lang.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, tabs, and Quote characters which require escaping inside Attribute values and converts their character representation to the appropriate entity reference suitable for XML attribute content.
static java.lang.String escapeText(EscapeStrategy strategy, java.lang.String eol, java.lang.String value)
          This will take the three pre-defined entities in XML 1.0 ('<', '>', and '&' - used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content.
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.
 java.lang.String getEncoding()
          Returns the configured output encoding.
 EscapeStrategy getEscapeStrategy()
          Returns the current escape strategy
 boolean getExpandEmptyElements()
          Returns whether empty elements are expanded.
 boolean getIgnoreTrAXEscapingPIs()
          Returns whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.
 java.lang.String getIndent()
          Returns the indent string in use.
 java.lang.String getLineSeparator()
          Returns the current line separator.
 boolean getOmitDeclaration()
          Returns whether the XML declaration will be omitted.
 boolean getOmitEncoding()
          Returns whether the XML declaration encoding will be omitted.
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.
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.
 Format.TextMode getTextMode()
          Returns the current text output style.
 boolean isSpecifiedAttributesOnly()
          Will Attributes defaulted from the DTD or XMLSchema be output
 Format setEncoding(java.lang.String encoding)
          Sets the output encoding.
 Format setEscapeStrategy(EscapeStrategy strategy)
          Sets the EscapeStrategy to use for character escaping.
 Format setExpandEmptyElements(boolean expandEmptyElements)
          This will set whether empty elements are expanded from <tagName/> to <tagName></tagName>.
 void setIgnoreTrAXEscapingPIs(boolean ignoreTrAXEscapingPIs)
          This will set whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.
 Format setIndent(java.lang.String indent)
          This will set the indent String to use; this is usually a String of empty spaces.
 Format setLineSeparator(LineSeparator separator)
          This will set the newline separator sequence.
 Format setLineSeparator(java.lang.String separator)
          This will set the newline separator (LineSeparator).
 Format setOmitDeclaration(boolean omitDeclaration)
          This will set whether the XML declaration (<?xml version="1.0"?>) will be omitted or not.
 Format setOmitEncoding(boolean omitEncoding)
          This will set whether the XML declaration (<?xml version="1.0" encoding="UTF-8"?>) includes the encoding of the document.
 void setSpecifiedAttributesOnly(boolean specifiedAttributesOnly)
          Set whether only those Attributes specified in the input XML should be output.
 Format setTextMode(Format.TextMode mode)
          This sets the text output style.
static java.lang.String trimBoth(java.lang.String str)
          Use the XML Specification definition of whitespace to trim the input value.
static java.lang.String trimLeft(java.lang.String str)
          Use the XML Specification definition of whitespace to Left-trim the input value.
static java.lang.String trimRight(java.lang.String str)
          Use the XML Specification definition of whitespace to Right-trim the input value.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getRawFormat

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:
a Format with no whitespace changes

getPrettyFormat

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:
a Format with whitespace beautification

getCompactFormat

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:
a Format with whitespace normalization

compact

public static final java.lang.String compact(java.lang.String str)
Use the XML Specification definition of whitespace to compact the input value. The value is trimmed, and any internal XML whitespace is replaced with a single ' ' space.

Parameters:
str - The value to compact.
Returns:
The compacted value
Since:
JDOM2

trimRight

public static final java.lang.String trimRight(java.lang.String str)
Use the XML Specification definition of whitespace to Right-trim the input value.

Parameters:
str - The value to trim.
Returns:
The value right-trimmed
Since:
JDOM2

trimLeft

public static final java.lang.String trimLeft(java.lang.String str)
Use the XML Specification definition of whitespace to Left-trim the input value.

Parameters:
str - The value to trim.
Returns:
The value left-trimmed
Since:
JDOM2

trimBoth

public static final java.lang.String trimBoth(java.lang.String str)
Use the XML Specification definition of whitespace to trim the input value.

Parameters:
str - The value to trim.
Returns:
The value trimmed
Since:
JDOM2

escapeAttribute

public static final java.lang.String escapeAttribute(EscapeStrategy strategy,
                                                     java.lang.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, tabs, and Quote characters which require escaping inside Attribute values and converts 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.

Parameters:
strategy - The EscapeStrategy to query.
value - String Attribute value to escape.
Returns:
The value appropriately escaped.
Throws:
IllegalDataException - if an entity can not be escaped

escapeText

public static final java.lang.String escapeText(EscapeStrategy strategy,
                                                java.lang.String eol,
                                                java.lang.String value)
This will take the three pre-defined entities in XML 1.0 ('<', '>', and '&' - used specifically in XML elements) and convert their character representation to the appropriate entity reference, suitable for XML element content. Further, some special characters (e.g. characters that are not valid in the current encoding) are converted to escaped representations. If the eol parameter is not null, then any internal newlines will be replaced with the specified eol sequence.

Parameters:
strategy - The EscapeStrategy
eol - The End-Of-Line sequence to be used (may be null).
value - The String to escape
Returns:
The input value escaped.
Throws:
IllegalDataException - if an entity can not be escaped
Since:
JDOM2

setEscapeStrategy

public Format setEscapeStrategy(EscapeStrategy strategy)
Sets the EscapeStrategy to use for character escaping.

Parameters:
strategy - the EscapeStrategy to use
Returns:
a pointer to this Format for chaining

getEscapeStrategy

public EscapeStrategy getEscapeStrategy()
Returns the current escape strategy

Returns:
the current escape strategy

setLineSeparator

public Format setLineSeparator(java.lang.String separator)
This will set the newline separator (LineSeparator). The default is \r\n.

Use the setLineSeparator(LineSeparator) method to set standard separators in an easier way.

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. All XML parsers are required to 'normalize' all the combinations of line seperators to just '\n'. As a result, if any JDOM component has an end-of-line-like value (e.g. '\r') in it then that value must be the result of an escaped value in the XML source document &#xD; or a value explicitly set with one of the Text value setters. Values in JDOM content that were explicitly set to be '\r' will always be escaped on XML Output.

The actual newline separator itself though can be set with this method. Any internal newlines in Text output will be represented by this end-of-line sequence. For example, the following code:

   Text txt = new Text("\r\n");
   XMLOutputter xout = new XMLOutputter();
   String result = xout.outputString(txt);
 
will produce the literal String sequence "&#xD;\r\n" because the original \r is escaped to be &#xD; and the original \n is replaced with the JDOM default Line Separator "\r\n".

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, as well as any newlines embedded within existing text content.

Setting the indent to be null will disable end-of-line processing for any formatting, but will not affect substitution of embedded \n. Setting this value to null or the empty string will disable all end-of-line modifications.

Parameters:
separator - String line separator to use.
Returns:
a pointer to this Format for chaining
See Also:
setTextMode(org.jdom2.output.Format.TextMode), setLineSeparator(LineSeparator)

setLineSeparator

public Format setLineSeparator(LineSeparator separator)
This will set the newline separator sequence.

This method differes from setLineSeparator(String) slightly in that, to disable end-of-line processing you should call:

 Format.setLinewSeparator(LineSeparator.NONE);
 

Parameters:
separator - LineSeparator line separator to us
Returns:
a pointer to this Format for chaining
Since:
JDOM2
See Also:
for comprehensive notes.

getLineSeparator

public java.lang.String getLineSeparator()
Returns the current line separator.

Returns:
the current line separator

setOmitEncoding

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 indicating whether or not the XML declaration should indicate the document encoding.
Returns:
a pointer to this Format for chaining

getOmitEncoding

public boolean getOmitEncoding()
Returns whether the XML declaration encoding will be omitted.

Returns:
whether the XML declaration encoding will be omitted

setOmitDeclaration

public Format setOmitDeclaration(boolean omitDeclaration)
This will set whether the XML declaration (<?xml version="1.0"?>) will be omitted or not. It is common to omit this in uses such as SOAP and XML-RPC calls.

Parameters:
omitDeclaration - boolean indicating whether or not the XML declaration should be omitted.
Returns:
a pointer to this Format for chaining

getOmitDeclaration

public boolean getOmitDeclaration()
Returns whether the XML declaration will be omitted.

Returns:
whether the XML declaration will be omitted

setExpandEmptyElements

public Format setExpandEmptyElements(boolean expandEmptyElements)
This will set whether empty elements are expanded from <tagName/> to <tagName></tagName>.

Parameters:
expandEmptyElements - boolean indicating whether or not empty elements should be expanded.
Returns:
a pointer to this Format for chaining

getExpandEmptyElements

public boolean getExpandEmptyElements()
Returns whether empty elements are expanded.

Returns:
whether empty elements are expanded

setIgnoreTrAXEscapingPIs

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 indicating whether or not TrAX ouput escaping PIs are ignored.
See Also:
Result.PI_ENABLE_OUTPUT_ESCAPING, Result.PI_DISABLE_OUTPUT_ESCAPING

getIgnoreTrAXEscapingPIs

public boolean getIgnoreTrAXEscapingPIs()
Returns whether JAXP TrAX processing instructions for disabling/enabling output escaping are ignored.

Returns:
whether or not TrAX ouput escaping PIs are ignored.

setTextMode

public Format setTextMode(Format.TextMode mode)
This sets the text output style. Options are available as static Format.TextMode instances. The default is Format.TextMode.PRESERVE.

Parameters:
mode - The TextMode to set.
Returns:
a pointer to this Format for chaining

getTextMode

public Format.TextMode getTextMode()
Returns the current text output style.

Returns:
the current text output style

setIndent

public Format setIndent(java.lang.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 to use for indentation.
Returns:
a pointer to this Format for chaining

getIndent

public java.lang.String getIndent()
Returns the indent string in use.

Returns:
the indent string in use

setEncoding

public Format setEncoding(java.lang.String encoding)
Sets the output encoding. The name should be an accepted XML encoding.

Parameters:
encoding - the encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII"
Returns:
a pointer to this Format for chaining

getEncoding

public java.lang.String getEncoding()
Returns the configured output encoding.

Returns:
the output encoding

isSpecifiedAttributesOnly

public boolean isSpecifiedAttributesOnly()
Will Attributes defaulted from the DTD or XMLSchema be output

Returns:
true if the defaulted Attributes will be output

setSpecifiedAttributesOnly

public void setSpecifiedAttributesOnly(boolean specifiedAttributesOnly)
Set whether only those Attributes specified in the input XML should be output. Other Attributes (those defaulted or 'fixed' in the DTD or XMLSchema) should be ignored.

Parameters:
specifiedAttributesOnly - true if the defaulted Attributes should be ignored, false if they should be output

clone

public Format clone()
Overrides:
clone in class java.lang.Object

JDOM
2.0.5

Copyright 2013 Jason Hunter, Brett McLaughlin. All Rights Reserved.