Class SMInputFactory

java.lang.Object
org.codehaus.staxmate.SMInputFactory

public final class SMInputFactory extends 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.
  • Field Details

    • _staxFactory

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

  • Method Details

    • getStaxFactory

      public 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(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(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(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(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(URL url) throws XMLStreamException
      Method for constructing Stax stream reader to read contents of specified URL, using Stax input factory this StaxMate factory was constructed with.
      Throws:
      XMLStreamException
    • createStax2Reader

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

      public org.codehaus.stax2.XMLStreamReader2 createStax2Reader(byte[] data, int offset, int len) throws 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:
      XMLStreamException
    • createStax2Reader

      public org.codehaus.stax2.XMLStreamReader2 createStax2Reader(InputStream in) throws 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:
      XMLStreamException
    • createStax2Reader

      public org.codehaus.stax2.XMLStreamReader2 createStax2Reader(Reader r) throws 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:
      XMLStreamException
    • rootElementCursor

      public SMHierarchicCursor rootElementCursor(URL url) throws 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:
      XMLStreamException
    • rootElementCursor

      public SMHierarchicCursor rootElementCursor(File f) throws 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:
      XMLStreamException
    • rootElementCursor

      public SMHierarchicCursor rootElementCursor(byte[] data, int offset, int len) throws 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:
      XMLStreamException
    • rootElementCursor

      public SMHierarchicCursor rootElementCursor(InputStream in) throws 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:
      XMLStreamException
    • rootElementCursor

      public SMHierarchicCursor rootElementCursor(Reader r) throws 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:
      XMLStreamException
    • flatteningCursor

      public SMFlatteningCursor flatteningCursor(File input, SMFilter f) throws XMLStreamException
      Throws:
      XMLStreamException
    • flatteningCursor

      public SMFlatteningCursor flatteningCursor(URL input, SMFilter f) throws XMLStreamException
      Throws:
      XMLStreamException
    • flatteningCursor

      public SMFlatteningCursor flatteningCursor(InputStream input, SMFilter f) throws XMLStreamException
      Throws:
      XMLStreamException
    • flatteningCursor

      public SMFlatteningCursor flatteningCursor(Reader r, SMFilter f) throws XMLStreamException
      Throws:
      XMLStreamException
    • getGlobalSMInputFactory

      public static SMInputFactory getGlobalSMInputFactory() throws 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:
      FactoryConfigurationError - If there are problems with configuration of Stax input factory (most likely because there is no implementation available)
    • getGlobalXMLInputFactory

      public static XMLInputFactory getGlobalXMLInputFactory() throws 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:
      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(XMLStreamReader sr)