org.codehaus.staxmate

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.

Author:

Tatu Saloranta

Constructor Summary

Constructors

Constructor and Description
SMInputFactory(XMLInputFactory staxF)

Method Summary

Methods

Modifier and Type	Method and 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(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(InputStream in) Method for constructing Stax stream reader to read contents accessible through InputStream provided.
org.codehaus.stax2.XMLStreamReader2	createStax2Reader(Reader r) Method for constructing Stax stream reader to read contents accessible through Reader provided.
org.codehaus.stax2.XMLStreamReader2	createStax2Reader(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(File input, SMFilter f)
SMFlatteningCursor	flatteningCursor(InputStream input, SMFilter f)
SMFlatteningCursor	flatteningCursor(Reader r, SMFilter f)
SMFlatteningCursor	flatteningCursor(URL input, SMFilter f)
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.
static SMInputFactory	getGlobalSMInputFactory() Convenience method that will get a lazily constructed shared SMInputFactory instance.
static XMLInputFactory	getGlobalXMLInputFactory() Convenience method that will get a lazily constructed shared XMLInputFactory instance.
XMLInputFactory	getStaxFactory() Accessor for getting the Stax input factory that this input factory uses for constructing XMLStreamReader instances it needs.
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.
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.
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(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(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(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(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(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(XMLStreamReader sr)

Methods inherited from class java.lang.Object

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

Constructor Detail

SMInputFactory

public SMInputFactory(XMLInputFactory staxF)

Method Detail

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)