Class SMInputFactory
- java.lang.Object
-
- org.codehaus.staxmate.SMInputFactory
-
public final class SMInputFactory extends java.lang.Object
Factory class used to createSMInputCursor
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.
- 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
-
-
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 sharedSMInputFactory
instance.static javax.xml.stream.XMLInputFactory
getGlobalXMLInputFactory()
Convenience method that will get a lazily constructed sharedXMLInputFactory
instance.javax.xml.stream.XMLInputFactory
getStaxFactory()
Accessor for getting the Stax input factory that this input factory uses for constructingXMLStreamReader
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)
-
-
-
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.
-
-
Method Detail
-
getStaxFactory
public javax.xml.stream.XMLInputFactory getStaxFactory()
Accessor for getting the Stax input factory that this input factory uses for constructingXMLStreamReader
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 usef
- (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 usef
- (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 sharedSMInputFactory
instance. Instance is built using similarly sharedXMLInputFactory
instance (which is accessed usinggetGlobalXMLInputFactory()
). See notes ongetGlobalXMLInputFactory()
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 sharedXMLInputFactory
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)
-
-