org.codehaus.stax2
Class XMLInputFactory2

java.lang.Object
  extended by javax.xml.stream.XMLInputFactory
      extended by org.codehaus.stax2.XMLInputFactory2
All Implemented Interfaces:
XMLStreamProperties
Direct Known Subclasses:
WstxInputFactory

public abstract class XMLInputFactory2
extends javax.xml.stream.XMLInputFactory
implements XMLStreamProperties

Extension of XMLInputFactory that adds some convenience factory methods as new standard properties that conforming stream reader factory and instance implementations need to recognize, and preferably support. There are also some profile-based configuration methods which allow implementations to set proper goal-based values for custom properties.
NOTE: although actual values for the property names are visible, implementations should try to use the symbolic constants defined here instead, to avoid typos.


Field Summary
static java.lang.String P_AUTO_CLOSE_INPUT
          Whether stream reader is to close the underlying input source (input stream, reader) when stream reader is closed.
static java.lang.String P_INTERN_NAMES
          Whether name symbols (element, attribute, entity and notation names, namespace prefixes) should be interned or not (or when querying an instance, whether the instance will guarantee that the names will be intern()ed).
static java.lang.String P_INTERN_NS_URIS
          Whether namespace URIs parsed should be interned or not (or when querying an instance, whether the instance will guarantee that the URIs will be intern()ed).
static java.lang.String P_PRESERVE_LOCATION
          Property that determines whether stream reader instances are required to try to keep track of the parser Location in the input documents.
static java.lang.String P_REPORT_CDATA
          Whether cursor-based reader will ever generate CDATA events; if true, CDATA events may be generated for non-coalesced CDATA sections.
static java.lang.String P_REPORT_PROLOG_WHITESPACE
          Whether reader will generate 'ignorable white space' events during prolog and epilog (before and after the main XML root element); if true, will generate those events; if false, will just ignore white space in these parts of the parsed document.
 
Fields inherited from class javax.xml.stream.XMLInputFactory
ALLOCATOR, IS_COALESCING, IS_NAMESPACE_AWARE, IS_REPLACING_ENTITY_REFERENCES, IS_SUPPORTING_EXTERNAL_ENTITIES, IS_VALIDATING, REPORTER, RESOLVER, SUPPORT_DTD
 
Fields inherited from interface org.codehaus.stax2.XMLStreamProperties
XSP_IMPLEMENTATION_NAME, XSP_IMPLEMENTATION_VERSION, XSP_NAMESPACE_AWARE, XSP_PROBLEM_REPORTER, XSP_SUPPORT_XMLID, XSP_SUPPORTS_XML11, XSP_V_XMLID_FULL, XSP_V_XMLID_NONE, XSP_V_XMLID_TYPING
 
Constructor Summary
protected XMLInputFactory2()
           
 
Method Summary
abstract  void configureForConvenience()
          Method to call to make Reader created be as "convenient" to use as possible; ie try to avoid having to deal with some of things like segmented text chunks.
abstract  void configureForLowMemUsage()
          Method to call to minimize the memory usage of the stream/event reader; both regarding Objects created, and the temporary memory usage during parsing.
abstract  void configureForRoundTripping()
          Method to call to make Reader try to preserve as much of input formatting as possible, so that round-tripping would be as lossless as possible.
abstract  void configureForSpeed()
          Method to call to make the Reader created be as fast as possible reading documents, especially for long-running processes where caching is likely to help.
abstract  void configureForXmlConformance()
          Method to call to make Reader created conform as closely to XML standard as possible, doing all checks and transformations mandated by the XML specification (linefeed conversions, attr value normalizations).
abstract  XMLEventReader2 createXMLEventReader(java.io.File f)
          Convenience factory method that allows for parsing a document stored in the specified file.
abstract  XMLEventReader2 createXMLEventReader(java.net.URL src)
          Factory method that allows for parsing a document accessible via specified URL.
abstract  XMLStreamReader2 createXMLStreamReader(java.io.File f)
          Convenience factory method that allows for parsing a document stored in the specified file.
abstract  XMLStreamReader2 createXMLStreamReader(java.net.URL src)
          Factory method that allows for parsing a document accessible via specified URL.
 
Methods inherited from class javax.xml.stream.XMLInputFactory
createFilteredReader, createFilteredReader, createXMLEventReader, createXMLEventReader, createXMLEventReader, createXMLEventReader, createXMLEventReader, createXMLEventReader, createXMLEventReader, createXMLStreamReader, createXMLStreamReader, createXMLStreamReader, createXMLStreamReader, createXMLStreamReader, createXMLStreamReader, getEventAllocator, getProperty, getXMLReporter, getXMLResolver, isPropertySupported, newInstance, newInstance, setEventAllocator, setProperty, setXMLReporter, setXMLResolver
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

P_REPORT_PROLOG_WHITESPACE

public static final java.lang.String P_REPORT_PROLOG_WHITESPACE
Whether reader will generate 'ignorable white space' events during prolog and epilog (before and after the main XML root element); if true, will generate those events; if false, will just ignore white space in these parts of the parsed document.

Turning this feature off may give slight performance improvement, although usually effect should be negligible. This option is usually only turned on when round-trip output should be as similar to input as possible.

Default value for this setting is implementation dependant.

See Also:
Constant Field Values

P_REPORT_CDATA

public static final java.lang.String P_REPORT_CDATA
Whether cursor-based reader will ever generate CDATA events; if true, CDATA events may be generated for non-coalesced CDATA sections. If false, all CDATA sections are reported as CHARACTERS types. It may still be possible for event methods to distinguish between underlying type, but event type code will be reported as CHARACTERS.

State of property does not have any effect on performance.

Default value for this setting is implementation dependant.

See Also:
Constant Field Values

P_INTERN_NAMES

public static final java.lang.String P_INTERN_NAMES
Whether name symbols (element, attribute, entity and notation names, namespace prefixes) should be interned or not (or when querying an instance, whether the instance will guarantee that the names will be intern()ed). Interning generally makes access faster (both internal and externally), and saves memory, but may add some overhead for processing.

See Also:
Constant Field Values

P_INTERN_NS_URIS

public static final java.lang.String P_INTERN_NS_URIS
Whether namespace URIs parsed should be interned or not (or when querying an instance, whether the instance will guarantee that the URIs will be intern()ed). Interning can make access by fully-qualified name faster as well as save memory, but it can also add some overhead when encountering a namespace URI for the first time.

Default value for this setting is implementation dependant.

See Also:
Constant Field Values

P_PRESERVE_LOCATION

public static final java.lang.String P_PRESERVE_LOCATION
Property that determines whether stream reader instances are required to try to keep track of the parser Location in the input documents.

When turned on, the stream reader should try to do its best to keep track of the locations, to be able to properly create XMLEvent objects with accurate Location information. Similarly, implementation should keep track of the location for error reporting purposes, and include this information within XMLStreamException instances.

When turned off, implementations are allowed to optimize things, and only keep/pass partial Location information, or even none at all. Implementations are still encouraged to keep some location information for error reporting purposes, even if they do not maintain accurate XMLEvent locations, or exact byte/character offsets.

Default value for this setting is true.

See Also:
Constant Field Values

P_AUTO_CLOSE_INPUT

public static final java.lang.String P_AUTO_CLOSE_INPUT
Whether stream reader is to close the underlying input source (input stream, reader) when stream reader is closed. Basic StAX2 specification mandates this feature to be set to false by default (for sources that are passed by the application).

Note: if set to true, readers are also allowed (but not required) to close the underlying input source when they do not need it any more, for example when encountering EOF, or when throwing an unrecoverable parsing exception

See Also:
Constant Field Values
Constructor Detail

XMLInputFactory2

protected XMLInputFactory2()
Method Detail

createXMLEventReader

public abstract XMLEventReader2 createXMLEventReader(java.net.URL src)
                                              throws javax.xml.stream.XMLStreamException
Factory method that allows for parsing a document accessible via specified URL. Note that URL may refer to all normal URL accessible resources, from files to web- and ftp-accessible documents.

Throws:
javax.xml.stream.XMLStreamException

createXMLEventReader

public abstract XMLEventReader2 createXMLEventReader(java.io.File f)
                                              throws javax.xml.stream.XMLStreamException
Convenience factory method that allows for parsing a document stored in the specified file.

Throws:
javax.xml.stream.XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader2 createXMLStreamReader(java.net.URL src)
                                                throws javax.xml.stream.XMLStreamException
Factory method that allows for parsing a document accessible via specified URL. Note that URL may refer to all normal URL accessible resources, from files to web- and ftp-accessible documents.

Throws:
javax.xml.stream.XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader2 createXMLStreamReader(java.io.File f)
                                                throws javax.xml.stream.XMLStreamException
Convenience factory method that allows for parsing a document stored in the specified file.

Throws:
javax.xml.stream.XMLStreamException

configureForXmlConformance

public abstract void configureForXmlConformance()
Method to call to make Reader created conform as closely to XML standard as possible, doing all checks and transformations mandated by the XML specification (linefeed conversions, attr value normalizations).

Regarding the default StAX property settings, implementations are suggested to do following:

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately, to be as strict as possible with regards to XML specification mandated checks and transformations.


configureForConvenience

public abstract void configureForConvenience()
Method to call to make Reader created be as "convenient" to use as possible; ie try to avoid having to deal with some of things like segmented text chunks. This may incur some slight performance penalties, but should not affect XML conformance.

Regarding the default StAX property settings, implementations are suggested to do following:

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.


configureForSpeed

public abstract void configureForSpeed()
Method to call to make the Reader created be as fast as possible reading documents, especially for long-running processes where caching is likely to help. This means reducing amount of information collected (ignorable white space in prolog/epilog, accurate Location information for Event API), and possibly even including simplifying handling of XML-specified transformations (skip attribute value and text linefeed normalization). Potential downsides are somewhat increased memory usage (for full-sized input buffers), and reduced XML conformance (will not do some of transformations).

Regarding the default StAX property settings, implementations are suggested to do following:

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.


configureForLowMemUsage

public abstract void configureForLowMemUsage()
Method to call to minimize the memory usage of the stream/event reader; both regarding Objects created, and the temporary memory usage during parsing. This generally incurs some performance penalties, due to using smaller input buffers.

Regarding the default StAX property settings, implementations are suggested to do following:

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately so that the memory usage is minimized.


configureForRoundTripping

public abstract void configureForRoundTripping()
Method to call to make Reader try to preserve as much of input formatting as possible, so that round-tripping would be as lossless as possible. This means that the matching writer should be able to reproduce output as closely matching input format as possible (most implementations won't be able to provide 100% vis-a-vis; white space between attributes is generally lost, as well as use of character entities).

Regarding the default StAX property settings, implementations are suggested to do following:

All the other standard settings should be left as is.

In addition, implementations should set implementation-dependant settings appropriately as well.