Class Format

  • All Implemented Interfaces:
    java.lang.Cloneable

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

    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 Format.TextMode for details.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) class  Format.DefaultEscapeStrategy
      Handle common charsets quickly and easily.
      static class  Format.TextMode
      Class to signify how text should be handled on output.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) java.lang.String encoding
      The encoding format
      (package private) org.jdom.output.EscapeStrategy escapeStrategy
      entity escape logic
      (package private) boolean expandEmptyElements
      Whether or not to expand empty elements to <tagName></tagName> - default is false
      (package private) boolean ignoreTrAXEscapingPIs
      Whether TrAX output escaping disabling/enabling PIs are ignored or processed - default is false
      (package private) java.lang.String indent
      The default indent is no spaces (as original document)
      (package private) java.lang.String lineSeparator
      New line separator
      (package private) Format.TextMode mode
      text handling mode
      (package private) boolean omitDeclaration
      Whether or not to output the XML declaration - default is false
      (package private) boolean omitEncoding
      Whether or not to output the encoding in the XML declaration - default is false
      private static java.lang.String STANDARD_ENCODING
      standard encoding
      private static java.lang.String STANDARD_INDENT
      standard value to indent by, if we are indenting
      private static java.lang.String STANDARD_LINE_SEPARATOR
      standard string with which to end a line
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Format()
      Creates a new Format instance with default (raw) behavior.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.lang.Object clone()  
      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.
      org.jdom.output.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.
      Format setEncoding​(java.lang.String encoding)
      Sets the output encoding.
      Format setEscapeStrategy​(org.jdom.output.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​(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"?gt;) 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.
      Format setTextMode​(Format.TextMode mode)
      This sets the text output style.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • STANDARD_INDENT

        private static final java.lang.String STANDARD_INDENT
        standard value to indent by, if we are indenting
        See Also:
        Constant Field Values
      • STANDARD_LINE_SEPARATOR

        private static final java.lang.String STANDARD_LINE_SEPARATOR
        standard string with which to end a line
        See Also:
        Constant Field Values
      • STANDARD_ENCODING

        private static final java.lang.String STANDARD_ENCODING
        standard encoding
        See Also:
        Constant Field Values
      • indent

        java.lang.String indent
        The default indent is no spaces (as original document)
      • lineSeparator

        java.lang.String lineSeparator
        New line separator
      • encoding

        java.lang.String encoding
        The encoding format
      • omitDeclaration

        boolean omitDeclaration
        Whether or not to output the XML declaration - default is false
      • omitEncoding

        boolean omitEncoding
        Whether or not to output the encoding in the XML declaration - default is false
      • expandEmptyElements

        boolean expandEmptyElements
        Whether or not to expand empty elements to <tagName></tagName> - default is false
      • ignoreTrAXEscapingPIs

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

        org.jdom.output.EscapeStrategy escapeStrategy
        entity escape logic
    • Constructor Detail

      • Format

        private Format()
        Creates a new Format instance with default (raw) behavior.
    • 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
      • setEscapeStrategy

        public Format setEscapeStrategy​(org.jdom.output.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 org.jdom.output.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. 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 set TextMode.NORMALIZE, then the newlines will be output verbatim, as "\n" which is how parsers normalize them.

        Parameters:
        separator - String line separator to use.
        Returns:
        a pointer to this Format for chaining
        See Also:
        setTextMode(org.apache.maven.archetype.common.util.Format.TextMode)
      • 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"?gt;) 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.
      • 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 null, or the empty string (""), then no indentation will happen. 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
      • clone

        protected java.lang.Object clone()
        Overrides:
        clone in class java.lang.Object