org.codehaus.staxmate
Class SMInputFactory

java.lang.Object
  org.codehaus.staxmate.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_ELEEMENT) 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

SMInputFactory(javax.xml.stream.XMLInputFactory staxF)

Method Summary

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.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.
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()
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.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.

Methods inherited from class java.lang.Object

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

Constructor Detail

SMInputFactory

public SMInputFactory(javax.xml.stream.XMLInputFactory staxF)

Method Detail

getStaxFactory

public javax.xml.stream.XMLInputFactory getStaxFactory()

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 constucted 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 of specified File.

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

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)