Class SMInputFactory


  • public final class SMInputFactory
    extends java.lang.Object
    Factory class used to create SMInputCursor instances. Cursor come in two major flavors: "nested" and "flattening" cursors.

    Nested cursor are used to iterate a single level nested events, so they can only traverse over immediate children of the event (generally, START_ELEMENT) that the parent cursor points to. Flattening cursors on the other hand traverse over all the descendants (children, children of children etc) of the parent START_ELEMENT. One additional difference is that the flattening cursors do expose END_ELEMENTS so that matching of actual levels is still possible.

    Beyond nested/flat (aka "child vs descendant") cursors, there are additional varieties, such as:

    • Filtered cursors: these will only expose events you want to see, and silently skip any other events. Most commonly needed ones (element-only, text-only, element-and-text-only; all of which skip comments, processing instructions) exist for your convenience using SMFilterFactory. Filters are passed to the factory methods.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  SMInputFactory.SMFactoryAccessor
      Helper class used for implementing efficient lazy instantiation of the global StaxMate input factory.
      private static class  SMInputFactory.XmlFactoryAccessor
      Helper class used for implementing efficient lazy instantiation of the global xml stream input factory.
    • Field Summary

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

      Constructors 
      Constructor Description
      SMInputFactory​(javax.xml.stream.XMLInputFactory staxF)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected static SMFlatteningCursor constructFlattening​(org.codehaus.stax2.XMLStreamReader2 sr, SMFilter f)  
      protected static SMHierarchicCursor constructHierarchic​(org.codehaus.stax2.XMLStreamReader2 sr, SMFilter f)  
      org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(byte[] data, int offset, int len)
      Method for constructing Stax stream reader to read contents of (portion of) specified byte array, using Stax input factory this StaxMate factory was constructed with.
      org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.File f)
      Method for constructing Stax stream reader to read contents of specified file, using Stax input factory this StaxMate factory was constructed with.
      org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.InputStream in)
      Method for constructing Stax stream reader to read contents accessible through InputStream provided.
      org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.Reader r)
      Method for constructing Stax stream reader to read contents accessible through Reader provided.
      org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.net.URL url)
      Method for constructing Stax stream reader to read contents of specified URL, using Stax input factory this StaxMate factory was constructed with.
      SMFlatteningCursor flatteningCursor​(java.io.File input, SMFilter f)  
      SMFlatteningCursor flatteningCursor​(java.io.InputStream input, SMFilter f)  
      SMFlatteningCursor flatteningCursor​(java.io.Reader r, SMFilter f)  
      SMFlatteningCursor flatteningCursor​(java.net.URL input, SMFilter f)  
      static SMFlatteningCursor flatteningCursor​(javax.xml.stream.XMLStreamReader sr, SMFilter f)
      Static factory method used to construct root-level flattening (descendant) cursor, when starting to process an xml document or fragment.
      static SMInputFactory getGlobalSMInputFactory()
      Convenience method that will get a lazily constructed shared SMInputFactory instance.
      static javax.xml.stream.XMLInputFactory getGlobalXMLInputFactory()
      Convenience method that will get a lazily constructed shared XMLInputFactory instance.
      javax.xml.stream.XMLInputFactory getStaxFactory()
      Accessor for getting the Stax input factory that this input factory uses for constructing XMLStreamReader instances it needs.
      static SMHierarchicCursor hierarchicCursor​(javax.xml.stream.XMLStreamReader sr, SMFilter f)
      Static factory method used to construct root-level hierarchic (child) cursor, when starting to process an xml document or fragment.
      static SMHierarchicCursor rootCursor​(javax.xml.stream.XMLStreamReader sr)
      Convenience method that will construct and return a nested cursor that will iterate over root-level events (comments, PIs, root element), without filtering any events.
      SMHierarchicCursor rootElementCursor​(byte[] data, int offset, int len)
      Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      SMHierarchicCursor rootElementCursor​(java.io.File f)
      Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      SMHierarchicCursor rootElementCursor​(java.io.InputStream in)
      Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      SMHierarchicCursor rootElementCursor​(java.io.Reader r)
      Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      SMHierarchicCursor rootElementCursor​(java.net.URL url)
      Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      static SMHierarchicCursor rootElementCursor​(javax.xml.stream.XMLStreamReader sr)
      Convenience method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.
      protected static org.codehaus.stax2.XMLStreamReader2 wrapIfNecessary​(javax.xml.stream.XMLStreamReader sr)  
      • 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.XMLInputFactory _staxFactory
        Xml input stream factory used for constructing stream readers.
      • _stax2Factory

        final org.codehaus.stax2.XMLInputFactory2 _stax2Factory
        If the configured stax input factory implements Stax2 API, will contain upcast factory instance, otherwise null.
    • Constructor Detail

      • SMInputFactory

        public SMInputFactory​(javax.xml.stream.XMLInputFactory staxF)
    • Method Detail

      • getStaxFactory

        public javax.xml.stream.XMLInputFactory getStaxFactory()
        Accessor for getting the Stax input factory that this input factory uses for constructing XMLStreamReader instances it needs.
      • hierarchicCursor

        public static SMHierarchicCursor hierarchicCursor​(javax.xml.stream.XMLStreamReader sr,
                                                          SMFilter f)
        Static factory method used to construct root-level hierarchic (child) cursor, when starting to process an xml document or fragment. Additional cursors are usually constructed via methods within this cursor and its child cursors).
        Parameters:
        sr - Underlying stream reader cursor will use
        f - (optional) Filter to use for the cursor, if any; null means that no filtering will be done.
      • flatteningCursor

        public static SMFlatteningCursor flatteningCursor​(javax.xml.stream.XMLStreamReader sr,
                                                          SMFilter f)
        Static factory method used to construct root-level flattening (descendant) cursor, when starting to process an xml document or fragment. Additional cursors are usually constructed via methods within this cursor and its child cursors).
        Parameters:
        sr - Underlying stream reader cursor will use
        f - (optional) Filter to use for the cursor, if any; null means that no filtering will be done.
      • rootElementCursor

        public static SMHierarchicCursor rootElementCursor​(javax.xml.stream.XMLStreamReader sr)
        Convenience method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Method uses standard "element-only" filter from SMFilterFactory.

      • rootCursor

        public static SMHierarchicCursor rootCursor​(javax.xml.stream.XMLStreamReader sr)
        Convenience method that will construct and return a nested cursor that will iterate over root-level events (comments, PIs, root element), without filtering any events.

        Method uses standard "element-only" filter from SMFilterFactory.

      • createStax2Reader

        public org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.net.URL url)
                                                              throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream reader to read contents of specified URL, using Stax input factory this StaxMate factory was constructed with.
        Throws:
        javax.xml.stream.XMLStreamException
      • createStax2Reader

        public org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.File f)
                                                              throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream reader to read contents of specified file, using Stax input factory this StaxMate factory was constructed with.
        Throws:
        javax.xml.stream.XMLStreamException
      • createStax2Reader

        public org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(byte[] data,
                                                                     int offset,
                                                                     int len)
                                                              throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream reader to read contents of (portion of) specified byte array, using Stax input factory this StaxMate factory was constructed with.
        Throws:
        javax.xml.stream.XMLStreamException
      • createStax2Reader

        public org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.InputStream in)
                                                              throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream reader to read contents accessible through InputStream provided. Underlying stream reader is constructed using Stax factory this StaxMate factory was constructed with.

        NOTE: this method should only be used if no other overloaded methods matches input source. For example, if input comes from a file, then the method that takes File argument should be used instead. This because more specific methods can provide better error reporting and entity resolution support.

        Throws:
        javax.xml.stream.XMLStreamException
      • createStax2Reader

        public org.codehaus.stax2.XMLStreamReader2 createStax2Reader​(java.io.Reader r)
                                                              throws javax.xml.stream.XMLStreamException
        Method for constructing Stax stream reader to read contents accessible through Reader provided. Underlying stream reader is constructed using Stax factory this StaxMate factory was constructed with.

        NOTE: this method should only be used if no other overloaded methods matches input source. For example, if input comes from a file, then the method that takes File argument should be used instead. This because more specific methods can provide better error reporting and entity resolution support.

        Throws:
        javax.xml.stream.XMLStreamException
      • rootElementCursor

        public SMHierarchicCursor rootElementCursor​(java.net.URL url)
                                             throws javax.xml.stream.XMLStreamException
        Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Cursor is built based on Stax stream reader constructed to read contents of resource specified by the URL argument.

        Method uses standard "element-only" filter from SMFilterFactory.

        Throws:
        javax.xml.stream.XMLStreamException
      • rootElementCursor

        public SMHierarchicCursor rootElementCursor​(java.io.File f)
                                             throws javax.xml.stream.XMLStreamException
        Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Cursor is built based on Stax stream reader constructed to read contents of specified File.

        Method uses standard "element-only" filter from SMFilterFactory.

        Throws:
        javax.xml.stream.XMLStreamException
      • rootElementCursor

        public SMHierarchicCursor rootElementCursor​(byte[] data,
                                                    int offset,
                                                    int len)
                                             throws javax.xml.stream.XMLStreamException
        Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Cursor is built based on Stax stream reader constructed to read contents of the specified byte array.

        Method uses standard "element-only" filter from SMFilterFactory.

        Throws:
        javax.xml.stream.XMLStreamException
      • rootElementCursor

        public SMHierarchicCursor rootElementCursor​(java.io.InputStream in)
                                             throws javax.xml.stream.XMLStreamException
        Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Cursor is built based on Stax stream reader constructed to read contents via specified InputStream.

        Method uses standard "element-only" filter from SMFilterFactory.

        NOTE: this method should only be used if no other overloaded methods matches input source. For example, if input comes from a file, then the method that takes File argument should be used instead. This because more specific methods can provide better error reporting and entity resolution support.

        Throws:
        javax.xml.stream.XMLStreamException
      • rootElementCursor

        public SMHierarchicCursor rootElementCursor​(java.io.Reader r)
                                             throws javax.xml.stream.XMLStreamException
        Method that will construct and return a nested cursor that will only ever iterate to one node, that is, the root element of the document reader is reading.

        Cursor is built based on Stax stream reader constructed to read contents via specified Reader.

        Method uses standard "element-only" filter from SMFilterFactory.

        NOTE: this method should only be used if no other overloaded methods matches input source. For example, if input comes from a file, then the method that takes File argument should be used instead. This because more specific methods can provide better error reporting and entity resolution support.

        Throws:
        javax.xml.stream.XMLStreamException
      • flatteningCursor

        public SMFlatteningCursor flatteningCursor​(java.io.File input,
                                                   SMFilter f)
                                            throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • flatteningCursor

        public SMFlatteningCursor flatteningCursor​(java.net.URL input,
                                                   SMFilter f)
                                            throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • flatteningCursor

        public SMFlatteningCursor flatteningCursor​(java.io.InputStream input,
                                                   SMFilter f)
                                            throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • flatteningCursor

        public SMFlatteningCursor flatteningCursor​(java.io.Reader r,
                                                   SMFilter f)
                                            throws javax.xml.stream.XMLStreamException
        Throws:
        javax.xml.stream.XMLStreamException
      • getGlobalSMInputFactory

        public static SMInputFactory getGlobalSMInputFactory()
                                                      throws javax.xml.stream.FactoryConfigurationError
        Convenience method that will get a lazily constructed shared SMInputFactory instance. Instance is built using similarly shared XMLInputFactory instance (which is accessed using getGlobalXMLInputFactory()). See notes on getGlobalXMLInputFactory() 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 SMInputFactory (and usually hence global to a single JVM instance).

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

        public static javax.xml.stream.XMLInputFactory getGlobalXMLInputFactory()
                                                                         throws javax.xml.stream.FactoryConfigurationError
        Convenience method that will get a lazily constructed shared XMLInputFactory instance. Note that this instance should only be used IFF:
        • Default settings (namespace-aware, dtd-aware but not validating, non-coalescing) 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

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

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

        protected static final SMHierarchicCursor constructHierarchic​(org.codehaus.stax2.XMLStreamReader2 sr,
                                                                      SMFilter f)
      • constructFlattening

        protected static final SMFlatteningCursor constructFlattening​(org.codehaus.stax2.XMLStreamReader2 sr,
                                                                      SMFilter f)
      • wrapIfNecessary

        protected static final org.codehaus.stax2.XMLStreamReader2 wrapIfNecessary​(javax.xml.stream.XMLStreamReader sr)