Package org.codehaus.staxmate

Class SMOutputFactory

java.lang.Object
org.codehaus.staxmate.SMOutputFactory
public final class SMOutputFactory extends 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 final class 
    SMOutputFactory.SMFactoryAccessor
    Helper class used for implementing efficient lazy instantiation of the global StaxMate output factory.
    private static final 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) final org.codehaus.stax2.XMLOutputFactory2
    _stax2Factory
    If the configured stax factory implements Stax2 API, will contain upcast factory instance, otherwise null.
    (package private) final XMLOutputFactory
    _staxFactory
    Xml output stream factory used for constructing stream readers.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SMOutputFactory(XMLOutputFactory staxF)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    SMOutputDocument
    createOutputDocument(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(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(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(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(XMLStreamWriter sw, String version, 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(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(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(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(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(File f)
    Method for constructing Stax stream writer to write xml content to specified file.
    org.codehaus.stax2.XMLStreamWriter2
    createStax2Writer(OutputStream out)
    Method for constructing Stax stream writer to write xml content to specified output stream.
    org.codehaus.stax2.XMLStreamWriter2
    createStax2Writer(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 XMLOutputFactory
    getGlobalXMLOutputFactory()
    Convenience method that will get a lazily constructed shared XMLOutputFactory instance.
    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 Details

    • _staxFactory

      final 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 Details

  • Method Details

    • getStaxFactory

      public 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(XMLStreamWriter sw) throws 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:
      XMLStreamException

    • createOutputDocument

      public SMOutputDocument createOutputDocument(File f) throws 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:
      XMLStreamException

    • createOutputDocument

      public SMOutputDocument createOutputDocument(OutputStream out) throws 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:
      XMLStreamException

    • createOutputDocument

      public SMOutputDocument createOutputDocument(Writer w) throws 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:
      XMLStreamException

    • createOutputDocument

      public static SMOutputDocument createOutputDocument(XMLStreamWriter sw, String version, String encoding, boolean standAlone) throws 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:
      XMLStreamException

    • createOutputFragment

      public static SMRootFragment createOutputFragment(XMLStreamWriter sw) throws 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:
      XMLStreamException

    • createOutputFragment

      public SMRootFragment createOutputFragment(File resultFile) throws 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:
      XMLStreamException

    • createOutputFragment

      public SMRootFragment createOutputFragment(OutputStream out) throws 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:
      XMLStreamException

    • createOutputFragment

      public SMRootFragment createOutputFragment(Writer w) throws 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:
      XMLStreamException

    • createStax2Writer

      public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer(File f) throws 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:
      XMLStreamException

    • createStax2Writer

      public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer(OutputStream out) throws 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:
      XMLStreamException

    • createStax2Writer

      public org.codehaus.stax2.XMLStreamWriter2 createStax2Writer(Writer w) throws 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:
      XMLStreamException

    • getGlobalSMOutputFactory

      public static SMOutputFactory getGlobalSMOutputFactory() throws 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:
      FactoryConfigurationError - If there are problems with configuration of Stax output factory (most likely because there is no implementation available)

    • getGlobalXMLOutputFactory

      public static XMLOutputFactory getGlobalXMLOutputFactory() throws 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:
      XMLStreamException