test

The Java EE 5 Tutorial

StAX Factory Classes

The StAX factory classes. XMLInputFactory, XMLOutputFactory, and XMLEventFactory, let you define and configure implementation instances of XML stream reader, stream writer, and event classes.

XMLInputFactory Class

The XMLInputFactory class lets you configure implementation instances of XML stream reader processors created by the factory. New instances of the abstract class XMLInputFactory are created by calling the newInstance method on the class. The static method XMLInputFactory.newInstance is then used to create a new factory instance.

    Deriving from JAXP, the XMLInputFactory.newInstance method determines the specific XMLInputFactory implementation class to load by using the following lookup procedure:

  1. Use the javax.xml.stream.XMLInputFactory system property.

  2. Use the lib/xml.stream.properties file in the J2SE Java Runtime Environment (JRE) directory.

  3. Use the Services API, if available, to determine the classname by looking in the META-INF/services/javax.xml.stream.XMLInputFactory files in JAR files available to the JRE.

  4. Use the platform default XMLInputFactory instance.

After getting a reference to an appropriate XMLInputFactory, an application can use the factory to configure and create stream instances. Table 18–4 lists the properties supported by XMLInputFactory. See the StAX specification for a more detailed listing.

Table 18–4 javax.xml.stream.XMLInputFactory Properties

Property 

Description 

isValidating

Turns on implementation-specific validation. 

isCoalescing

(Required) Requires the processor to coalesce adjacent character data.

isNamespaceAware

Turns off namespace support. All implementations must support namespaces. Support for non-namespace-aware documents is optional. 

isReplacingEntityReferences

(Required) Requires the processor to replace internal entity references with their replacement value and report them as characters or the set of events that describe the entity.

isSupportingExternalEntities

(Required) Requires the processor to resolve external parsed entities.

reporter

(Required) Sets and gets the implementation of the XMLReporter interface.

resolver

(Required) Sets and gets the implementation of the XMLResolver interface.

allocator

(Required) Sets and gets the implementation of the XMLEventAllocator interface.

XMLOutputFactory Class

New instances of the abstract class XMLOutputFactory are created by calling the newInstance method on the class. The static method XMLOutputFactory.newInstance is then used to create a new factory instance. The algorithm used to obtain the instance is the same as for XMLInputFactory but references the javax.xml.stream.XMLOutputFactory system property.

XMLOutputFactory supports only one property, javax.xml.stream.isRepairingNamespaces. This property is required, and its purpose is to create default prefixes and associate them with Namespace URIs. See the StAX specification for more information.

XMLEventFactory Class

New instances of the abstract class XMLEventFactory are created by calling the newInstance method on the class. The static method XMLEventFactory.newInstance is then used to create a new factory instance. This factory references the javax.xml.stream.XMLEventFactory property to instantiate the factory. The algorithm used to obtain the instance is the same as for XMLInputFactory and XMLOutputFactory but references the javax.xml.stream.XMLEventFactory system property.

There are no default properties for XMLEventFactory.