Package org.codehaus.staxmate

Class SMOutputFactory

  • public final class SMOutputFactory
extends java.lang.Object
    Factory class used to create root-level outputter object (like SMOutputDocument and SMRootFragment) instances, which are roots (global for documents, or local for fragments) of output content.

    Note about life-cycle of root-level outputter objects: once you are done with a root-level outputter, you MUST call SMRootFragment.closeRoot() method to ensure that all content is flushed to the underlying stream writer

    Factory also has convenience method(s) for accessing a shared global instance of a default XMLOutputFactory.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  SMOutputFactory.SMFactoryAccessor
      Helper class used for implementing efficient lazy instantiation of the global StaxMate output factory.
      private static class  SMOutputFactory.XmlFactoryAccessor
      Separate helper class is used so that the shared factory instance is only created if needed: this happens if the accessor class needs to be instantiate, which in turn happens if the method for accessing the global output factory is called.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) org.codehaus.stax2.XMLOutputFactory2 _stax2Factory
      If the configured stax factory implements Stax2 API, will contain upcast factory instance, otherwise null.
      (package private) javax.xml.stream.XMLOutputFactory _staxFactory
      Xml output stream factory used for constructing stream readers.

    • Constructor Summary

      Constructors 
      Constructor Description
      SMOutputFactory​(javax.xml.stream.XMLOutputFactory staxF)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      SMOutputDocument createOutputDocument​(java.io.File f)
      Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).
      SMOutputDocument createOutputDocument​(java.io.OutputStream out)
      Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).
      SMOutputDocument createOutputDocument​(java.io.Writer w)
      Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).
      static SMOutputDocument createOutputDocument​(javax.xml.stream.XMLStreamWriter sw)
      Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).
      static SMOutputDocument createOutputDocument​(javax.xml.stream.XMLStreamWriter sw, java.lang.String version, java.lang.String encoding, boolean standAlone)
      Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).
      SMRootFragment createOutputFragment​(java.io.File resultFile)
      Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.
      SMRootFragment createOutputFragment​(java.io.OutputStream out)
      Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.
      SMRootFragment createOutputFragment​(java.io.Writer w)
      Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.
      static SMRootFragment createOutputFragment​(javax.xml.stream.XMLStreamWriter sw)
      Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.
      org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.File f)
      Method for constructing Stax stream writer to write xml content to specified file.
      org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.OutputStream out)
      Method for constructing Stax stream writer to write xml content to specified output stream.
      org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.Writer w)
      Method for constructing Stax stream writer to write xml content using specified Writer.
      static SMOutputFactory getGlobalSMOutputFactory()
      Convenience method that will get a lazily constructed shared SMOutputFactory instance.
      static javax.xml.stream.XMLOutputFactory getGlobalXMLOutputFactory()
      Convenience method that will get a lazily constructed shared XMLOutputFactory instance.
      javax.xml.stream.XMLOutputFactory getStaxFactory()
      Method for accessing Stax output factory this StaxMate output factory was constructed with.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • _staxFactory

        final javax.xml.stream.XMLOutputFactory _staxFactory
        Xml output stream factory used for constructing stream readers.

      • _stax2Factory

        final org.codehaus.stax2.XMLOutputFactory2 _stax2Factory
        If the configured stax factory implements Stax2 API, will contain upcast factory instance, otherwise null.

    • Constructor Detail

      • SMOutputFactory

        public SMOutputFactory​(javax.xml.stream.XMLOutputFactory staxF)

    • Method Detail

      • getStaxFactory

        public javax.xml.stream.XMLOutputFactory getStaxFactory()
        Method for accessing Stax output factory this StaxMate output factory was constructed with. Factory can be configured using normal property-based configuration methods.

      • createOutputDocument

        public static SMOutputDocument createOutputDocument​(javax.xml.stream.XMLStreamWriter sw)
                                             throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct fragments, for this purpose check out createOutputFragment(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputDocument

        public SMOutputDocument createOutputDocument​(java.io.File f)
                                      throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct fragments, for this purpose check out createOutputFragment(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputDocument

        public SMOutputDocument createOutputDocument​(java.io.OutputStream out)
                                      throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct fragments, for this purpose check out createOutputFragment(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputDocument

        public SMOutputDocument createOutputDocument​(java.io.Writer w)
                                      throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct fragments, for this purpose check out createOutputFragment(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputDocument

        public static SMOutputDocument createOutputDocument​(javax.xml.stream.XMLStreamWriter sw,
                                                    java.lang.String version,
                                                    java.lang.String encoding,
                                                    boolean standAlone)
                                             throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents a complete xml document including xml declaration and will contain root element plus other optional elements (doctype declaration, comment(s), PI(s)).

        Note: you can not use this method to construct fragments, for this purpose check out createOutputFragment(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputFragment

        public static SMRootFragment createOutputFragment​(javax.xml.stream.XMLStreamWriter sw)
                                           throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct actual documents, for this purpose check out createOutputDocument(javax.xml.stream.XMLStreamWriter).

        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputFragment

        public SMRootFragment createOutputFragment​(java.io.File resultFile)
                                    throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct actual documents, for this purpose check out createOutputDocument(javax.xml.stream.XMLStreamWriter).

        Parameters:
        resultFile - file xml contents get written to
        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputFragment

        public SMRootFragment createOutputFragment​(java.io.OutputStream out)
                                    throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct actual documents, for this purpose check out createOutputDocument(javax.xml.stream.XMLStreamWriter).

        Parameters:
        out - Output stream through with xml contents get written
        Throws:
        javax.xml.stream.XMLStreamException

      • createOutputFragment

        public SMRootFragment createOutputFragment​(java.io.Writer w)
                                    throws javax.xml.stream.XMLStreamException
        Factory method for constructing output object that represents root-level of an xml fragment; container that can contain non-element markup (comments, PIs), textual data and zero or more elements.

        Note that after you have completed output using the result object (and its children), you must call SMRootFragment.closeRoot() method to ensure that all the content is properly output via underlying stream writer.

        Note: you can not use this method to construct actual documents, for this purpose check out createOutputDocument(javax.xml.stream.XMLStreamWriter).

        Parameters:
        w - Writer used for writing xml contents
        Throws:
        javax.xml.stream.XMLStreamException

      • createStax2Writer

        public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.File f)
                                                      throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream writer to write xml content to specified file. Underlying stream writer will be constructed using Stax factory this StaxMate factory was constructed with.

        Encoding used will be UTF-8.

        Throws:
        javax.xml.stream.XMLStreamException

      • createStax2Writer

        public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.OutputStream out)
                                                      throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream writer to write xml content to specified output stream. Underlying stream writer will be constructed using Stax factory this StaxMate factory was constructed with.

        Encoding used will be UTF-8.

        Throws:
        javax.xml.stream.XMLStreamException

      • createStax2Writer

        public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer​(java.io.Writer w)
                                                      throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream writer to write xml content using specified Writer. Underlying stream writer will be constructed using Stax factory this StaxMate factory was constructed with.

        Encoding used will be UTF-8.

        Throws:
        javax.xml.stream.XMLStreamException

      • getGlobalSMOutputFactory

        public static SMOutputFactory getGlobalSMOutputFactory()
                                                throws javax.xml.stream.FactoryConfigurationError
        Convenience method that will get a lazily constructed shared SMOutputFactory instance. Instance is built using similarly shared XMLOutputFactory instance (which is accessed using getGlobalXMLOutputFactory()). See notes on getGlobalXMLOutputFactory() for limitations on when (if ever) you should use this method.

        Note that this single(ton) instance is global to the class loader that loaded SMOutputFactory (and usually hence global to a single JVM instance).

        Throws:
        javax.xml.stream.FactoryConfigurationError - If there are problems with configuration of Stax output factory (most likely because there is no implementation available)

      • getGlobalXMLOutputFactory

        public static javax.xml.stream.XMLOutputFactory getGlobalXMLOutputFactory()
                                                                   throws javax.xml.stream.XMLStreamException
        Convenience method that will get a lazily constructed shared XMLOutputFactory instance. Note that this instance should only be used iff:
        • Default settings (non-repairing) for the factory are acceptable
        • Settings of the factory are not modified: thread-safety of the factory instance is only guaranteed for factory methods, not for configuration change methods
        Throws:
        javax.xml.stream.XMLStreamException