Package org.apache.calcite.util

Class XmlOutput

  • public class XmlOutput
extends java.lang.Object
    Streaming XML output.

    Use this class to write XML to any streaming source. While the class itself is unstructured and doesn't enforce any DTD specification, use of the class does ensure that the output is syntactically valid XML.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) static class  XmlOutput.StringEscaper
      Utility for replacing special characters with escape sequences in strings.
      (package private) static class  XmlOutput.XMLAttrVector
      List of attribute names and values.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean alwaysQuoteCData  
      private boolean compact  
      private boolean glob  
      private boolean ignorePcdata  
      private int indent  
      private java.lang.String indentString  
      private boolean inTag
      Whether we have started but not finished a start tag.
      private java.io.PrintWriter out  
      private java.util.Deque<java.lang.String> tagStack  
      private int tagsWritten  

    • Constructor Summary

      Constructors 
      Constructor Description
      XmlOutput​(java.io.PrintWriter out)
      Constructs a new XmlOutput based on a PrintWriter.
      XmlOutput​(java.io.Writer out)
      Constructs a new XmlOutput based on any Writer.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void attribute​(java.lang.String name, java.lang.String value)
      Writes an attribute.
      void beginBeginTag​(java.lang.String tagName)  
      void beginNode()
      If we are currently inside the start tag, finishes it off.
      void beginTag​(java.lang.String tagName, XmlOutput.XMLAttrVector attributes)
      Starts writing a new tag to the stream.
      void cdata​(java.lang.String data)
      Writes a CDATA section.
      void cdata​(java.lang.String data, boolean quote)
      Writes a CDATA section (as cdata(String)).
      void content​(java.lang.String content)
      Writes content.
      private void displayIndent​(java.io.PrintWriter out, int indent)
      Private helper function to display a degree of indentation
      void emptyTag​(java.lang.String tagName, XmlOutput.XMLAttrVector attributes)
      Writes an empty tag to the stream.
      void endBeginTag​(java.lang.String tagName)  
      void endTag​(java.lang.String tagName)
      Completes a tag.
      private static java.lang.String escapeForQuoting​(java.lang.String val)  
      boolean getCompact()  
      boolean getIgnorePcdata()  
      void header()
      Write header.
      void header​(java.lang.String version)
      Write header, take version as input.
      int numTagsWritten()
      Get the total number of tags written
      void print​(java.lang.String s)
      Sends a string directly to the output stream, without escaping any characters.
      private static void printAtt​(java.io.PrintWriter pw, java.lang.String name, java.lang.String val)
      Print an XML attribute name and value for string val
      void setAlwaysQuoteCData​(boolean alwaysQuoteCData)
      Sets whether to always quote cdata segments (even if they don't contain special characters).
      void setCompact​(boolean compact)
      Sets or unsets the compact mode.
      void setGlob​(boolean glob)
      Sets whether to detect that tags are empty.
      void setIgnorePcdata​(boolean ignorePcdata)
      Sets whether to ignore unquoted text, such as whitespace.
      void setIndentString​(java.lang.String indentString)
      Sets the string to print for each level of indentation.
      private static void stringEncodeXML​(java.lang.String input, java.io.PrintWriter out)
      Encode a String for XML output, displaying it to a PrintWriter.
      private static boolean stringHasXMLSpecials​(java.lang.String input)
      Returns whether a string contains any XML special characters.
      void stringTag​(java.lang.String name, java.lang.String data)
      Writes a String tag; a tag containing nothing but a CDATA section.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • out

        private final java.io.PrintWriter out

      • tagStack

        private final java.util.Deque<java.lang.String> tagStack

      • indent

        private int indent

      • tagsWritten

        private int tagsWritten

      • compact

        private boolean compact

      • inTag

        private boolean inTag
        Whether we have started but not finished a start tag. This only happens if glob is true. The start tag is automatically closed when we start a child node. If there are no child nodes, endTag(java.lang.String) creates an empty tag.

    • Constructor Detail

      • XmlOutput

        public XmlOutput​(java.io.Writer out)
        Constructs a new XmlOutput based on any Writer.
        Parameters:
        out - the writer to which this XmlOutput generates results.

      • XmlOutput

        public XmlOutput​(java.io.PrintWriter out)
        Constructs a new XmlOutput based on a PrintWriter.
        Parameters:
        out - the writer to which this XmlOutput generates results.

    • Method Detail

      • displayIndent

        private void displayIndent​(java.io.PrintWriter out,
                           int indent)
        Private helper function to display a degree of indentation
        Parameters:
        out - the PrintWriter to which to display output.
        indent - the degree of indentation.

      • setCompact

        public void setCompact​(boolean compact)
        Sets or unsets the compact mode. Compact mode causes the generated XML to be free of extraneous whitespace and other unnecessary characters.
        Parameters:
        compact - true to turn on compact mode, or false to turn it off.

      • getCompact

        public boolean getCompact()

      • setIndentString

        public void setIndentString​(java.lang.String indentString)
        Sets the string to print for each level of indentation. The default is a tab. The value must not be null. Set this to the empty string to achieve no indentation (note that setCompact(boolean)(true) removes indentation and newlines).

      • setGlob

        public void setGlob​(boolean glob)
        Sets whether to detect that tags are empty.

      • setAlwaysQuoteCData

        public void setAlwaysQuoteCData​(boolean alwaysQuoteCData)
        Sets whether to always quote cdata segments (even if they don't contain special characters).

      • setIgnorePcdata

        public void setIgnorePcdata​(boolean ignorePcdata)
        Sets whether to ignore unquoted text, such as whitespace.

      • getIgnorePcdata

        public boolean getIgnorePcdata()

      • print

        public void print​(java.lang.String s)
        Sends a string directly to the output stream, without escaping any characters. Use with caution!

      • beginTag

        public void beginTag​(java.lang.String tagName,
                     XmlOutput.XMLAttrVector attributes)
        Starts writing a new tag to the stream. The tag's name must be given and its attributes should be specified by a fully constructed AttrVector object.
        Parameters:
        tagName - the name of the tag to write.
        attributes - an XMLAttrVector containing the attributes to include in the tag.

      • beginBeginTag

        public void beginBeginTag​(java.lang.String tagName)

      • endBeginTag

        public void endBeginTag​(java.lang.String tagName)

      • attribute

        public void attribute​(java.lang.String name,
                      java.lang.String value)
        Writes an attribute.

      • beginNode

        public void beginNode()
        If we are currently inside the start tag, finishes it off.

      • endTag

        public void endTag​(java.lang.String tagName)
        Completes a tag. This outputs the end tag corresponding to the last exposed beginTag. The tag name must match the name of the corresponding beginTag.
        Parameters:
        tagName - the name of the end tag to write.

      • emptyTag

        public void emptyTag​(java.lang.String tagName,
                     XmlOutput.XMLAttrVector attributes)
        Writes an empty tag to the stream. An empty tag is one with no tags inside it, although it may still have attributes.
        Parameters:
        tagName - the name of the empty tag.
        attributes - an XMLAttrVector containing the attributes to include in the tag.

      • cdata

        public void cdata​(java.lang.String data)
        Writes a CDATA section. Such sections always appear on their own line. The nature in which the CDATA section is written depends on the actual string content with respect to these special characters/sequences:
        • &
        • "
        • '
        • <
        • >
        Additionally, the sequence ]]> is special.
        • Content containing no special characters will be left as-is.
        • Content containing one or more special characters but not the sequence ]]> will be enclosed in a CDATA section.
        • Content containing special characters AND at least one ]]> sequence will be left as-is but have all of its special characters encoded as entities.
        These special treatment rules are required to allow cdata sections to contain XML strings which may themselves contain cdata sections. Traditional CDATA sections do not nest.

      • cdata

        public void cdata​(java.lang.String data,
                  boolean quote)
        Writes a CDATA section (as cdata(String)).
        Parameters:
        data - string to write
        quote - if true, quote in a <![CDATA[ ... ]]> regardless of the content of data; if false, quote only if the content needs it

      • stringTag

        public void stringTag​(java.lang.String name,
                      java.lang.String data)
        Writes a String tag; a tag containing nothing but a CDATA section.

      • content

        public void content​(java.lang.String content)
        Writes content.

      • header

        public void header()
        Write header. Use default version 1.0.

      • header

        public void header​(java.lang.String version)
        Write header, take version as input.

      • numTagsWritten

        public int numTagsWritten()
        Get the total number of tags written
        Returns:
        the total number of tags written to the XML stream.

      • printAtt

        private static void printAtt​(java.io.PrintWriter pw,
                             java.lang.String name,
                             java.lang.String val)
        Print an XML attribute name and value for string val

      • stringEncodeXML

        private static void stringEncodeXML​(java.lang.String input,
                                    java.io.PrintWriter out)
        Encode a String for XML output, displaying it to a PrintWriter. The String to be encoded is displayed, except that special characters are converted into entities.
        Parameters:
        input - a String to convert.
        out - a PrintWriter to which to write the results.

      • escapeForQuoting

        private static java.lang.String escapeForQuoting​(java.lang.String val)

      • stringHasXMLSpecials

        private static boolean stringHasXMLSpecials​(java.lang.String input)
        Returns whether a string contains any XML special characters.

        If this function returns true, the string will need to be encoded either using the stringEncodeXML function above or using a CDATA section. Note that MSXML has a nasty bug whereby whitespace characters outside of a CDATA section are lost when parsing. To avoid hitting this bug, this method treats many whitespace characters as "special".

        Parameters:
        input - the String to scan for XML special characters.
        Returns:
        true if the String contains any such characters.