Package org.jdom2.output

Class StAXEventOutputter

  • All Implemented Interfaces:
    java.lang.Cloneable
    public final class StAXEventOutputter
extends java.lang.Object
implements java.lang.Cloneable
    Outputs a JDOM document as a StAX XMLEventConsumer of bytes.

    The StAXStreamOutputter 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:

    All of the output*(...) methods will flush the destination XMLEventConsumer before returning, and none of them will close() the destination.

    To omit output of the declaration use Format.setOmitDeclaration(boolean). To omit printing of the encoding in the declaration use Format.setOmitEncoding(boolean).

    If changing the Format settings are insufficient for your output needs you can customise this StAXStreamOutputter further by setting a different StAXEventProcessor with the setStAXEventProcessor(StAXEventProcessor) method or an appropriate constructor. A fully-enabled Abstract class AbstractStAXEventProcessor is available to be further extended to your needs if all you want to do is tweak some details.

    Since:
    JDOM2
    Author:
    Rolf Lear

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      StAXEventOutputter clone()
      Returns a cloned copy of this StAXStreamOutputter.
      javax.xml.stream.XMLEventFactory getEventFactory()  
      Format getFormat()
      Returns the current format in use by the StAXStreamOutputter.
      StAXEventProcessor getStAXStream()
      Returns the current XMLOutputProcessor instance in use by the StAXStreamOutputter.
      void output​(java.util.List<? extends Content> list, javax.xml.stream.util.XMLEventConsumer out)
      This will handle printing out a list of nodes.
      void output​(CDATA cdata, javax.xml.stream.util.XMLEventConsumer out)
      Print out a CDATA node.
      void output​(Comment comment, javax.xml.stream.util.XMLEventConsumer out)
      Print out a Comment.
      void output​(DocType doctype, javax.xml.stream.util.XMLEventConsumer out)
      Print out the DocType.
      void output​(Document doc, javax.xml.stream.util.XMLEventConsumer out)
      This will print the Document to the given Writer.
      void output​(Element element, javax.xml.stream.util.XMLEventConsumer out)
      Print out an Element, including its Attributes, and all contained (child) elements, etc.
      void output​(EntityRef entity, javax.xml.stream.util.XMLEventConsumer out)
      Print out an EntityRef.
      void output​(ProcessingInstruction pi, javax.xml.stream.util.XMLEventConsumer out)
      Print out a ProcessingInstruction.
      void output​(Text text, javax.xml.stream.util.XMLEventConsumer out)
      Print out a Text node.
      void outputElementContent​(Element element, javax.xml.stream.util.XMLEventConsumer out)
      This will handle printing out an Element's content only, not including its tag, and attributes.
      void setEventFactory​(javax.xml.stream.XMLEventFactory myEventFactory)  
      void setFormat​(Format newFormat)
      Sets the new format logic for the StAXStreamOutputter.
      void setStAXEventProcessor​(StAXEventProcessor processor)
      Sets a new XMLOutputProcessor instance for this StAXStreamOutputter.
      java.lang.String toString()
      Return a string listing of the settings for this StAXStreamOutputter instance.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • StAXEventOutputter

        public StAXEventOutputter​(Format format,
                          StAXEventProcessor processor,
                          javax.xml.stream.XMLEventFactory eventfactory)
        This will create an StAXStreamOutputter with the specified format characteristics.

        Note: the format object is cloned internally before use. If you want to modify the Format after constructing the StAXStreamOutputter you can modify the Format instance getFormat() returns.

        Parameters:
        format - The Format instance to use. This instance will be cloned() and as a consequence, changes made to the specified format instance will not be reflected in this StAXStreamOutputter. A null input format indicates that StAXStreamOutputter should use the default Format.getRawFormat()
        processor - The XMLOutputProcessor to delegate output to. If null the StAXStreamOutputter will use the default XMLOutputProcessor.
        eventfactory - The factory to use to create XMLEvent instances.

      • StAXEventOutputter

        public StAXEventOutputter()
        This will create an StAXStreamOutputter with a default Format and XMLOutputProcessor.

      • StAXEventOutputter

        public StAXEventOutputter​(Format format)
        This will create an StAXStreamOutputter with the specified format characteristics.

        Note: the format object is cloned internally before use.

        Parameters:
        format - The Format instance to use. This instance will be cloned() and as a consequence, changes made to the specified format instance will not be reflected in this StAXStreamOutputter. A null input format indicates that StAXStreamOutputter should use the default Format.getRawFormat()

      • StAXEventOutputter

        public StAXEventOutputter​(StAXEventProcessor processor)
        This will create an StAXStreamOutputter with the specified XMLOutputProcessor.
        Parameters:
        processor - The XMLOutputProcessor to delegate output to. If null the StAXStreamOutputter will use the default XMLOutputProcessor.

      • StAXEventOutputter

        public StAXEventOutputter​(javax.xml.stream.XMLEventFactory eventfactory)
        This will create an StAXStreamOutputter with the specified XMLOutputProcessor.
        Parameters:
        eventfactory - The XMLEventFactory to use to create XMLEvent instances.

    • Method Detail

      • setFormat

        public void setFormat​(Format newFormat)
        Sets the new format logic for the StAXStreamOutputter. Note the Format object is cloned internally before use.
        Parameters:
        newFormat - the format to use for subsequent output
        See Also:
        getFormat()

      • getFormat

        public Format getFormat()
        Returns the current format in use by the StAXStreamOutputter. Note the Format object returned is not a clone of the one used internally, thus, an StAXStreamOutputter instance is able to have it's Format changed by changing the settings on the Format instance returned by this method.
        Returns:
        the current Format instance used by this StAXStreamOutputter.

      • getStAXStream

        public StAXEventProcessor getStAXStream()
        Returns the current XMLOutputProcessor instance in use by the StAXStreamOutputter.
        Returns:
        the current XMLOutputProcessor instance.

      • setStAXEventProcessor

        public void setStAXEventProcessor​(StAXEventProcessor processor)
        Sets a new XMLOutputProcessor instance for this StAXStreamOutputter. Note the processor object is expected to be thread-safe.
        Parameters:
        processor - the new XMLOutputProcesor to use for output

      • getEventFactory

        public javax.xml.stream.XMLEventFactory getEventFactory()
        Returns:
        the current XMLEventFactory used by this StAXEventOutputter

      • setEventFactory

        public void setEventFactory​(javax.xml.stream.XMLEventFactory myEventFactory)
        Parameters:
        myEventFactory - the XMLEventFactory to use for subsequent output.

      • output

        public final void output​(Document doc,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        This will print the 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.

        Parameters:
        doc - Document to format.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(DocType doctype,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out the DocType.
        Parameters:
        doctype - DocType to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(Element element,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out an Element, including its Attributes, and all contained (child) elements, etc.
        Parameters:
        element - Element to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • outputElementContent

        public final void outputElementContent​(Element element,
                                       javax.xml.stream.util.XMLEventConsumer out)
                                throws javax.xml.stream.XMLStreamException
        This will handle printing out an 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>".
        Parameters:
        element - Element to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(java.util.List<? extends Content> list,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        This will handle printing out a list of nodes. This can be useful for printing the content of an element that contains HTML, like "<description>JDOM is <b>fun>!</description>".
        Parameters:
        list - List of nodes.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(CDATA cdata,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out a CDATA node.
        Parameters:
        cdata - CDATA to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(Text text,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out a Text node. Perfoms the necessary entity escaping and whitespace stripping.
        Parameters:
        text - Text to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(Comment comment,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out a Comment.
        Parameters:
        comment - Comment to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(ProcessingInstruction pi,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out a ProcessingInstruction.
        Parameters:
        pi - ProcessingInstruction to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • output

        public final void output​(EntityRef entity,
                         javax.xml.stream.util.XMLEventConsumer out)
                  throws javax.xml.stream.XMLStreamException
        Print out an EntityRef.
        Parameters:
        entity - EntityRef to output.
        out - XMLEventConsumer to use.
        Throws:
        javax.xml.stream.XMLStreamException - - if there's any problem writing.
        java.lang.NullPointerException - if the specified content is null.

      • clone

        public StAXEventOutputter clone()
        Returns a cloned copy of this StAXStreamOutputter.
        Overrides:
        clone in class java.lang.Object

      • toString

        public java.lang.String toString()
        Return a string listing of the settings for this StAXStreamOutputter instance.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string listing the settings for this StAXStreamOutputter instance