javolution.xml.stream

Class XMLInputFactory

Object

XMLInputFactory

public abstract class XMLInputFactory
extends Object

The class represents the factory for getting XMLStreamReader intances.

The default implementation automatically recycles any reader which has been closed.

Usage example:

 
     // Lets read a CharSequence input.
     String xml = "...";
     CharSequenceReader in = new CharSequenceReader().setInput(xml);

     // Creates a factory of readers coalescing adjacent character data.
     XMLInputFactory factory = XMLInputFactory.newInstance();
     factory.setProperty(XMLInputFactory.IS_COALESCING, true);
     
     // Creates a new reader (potentially recycled).
     XMLStreamReader reader = factory.createXMLStreamReader(in);
     
     // Parses XML.
     for (int e=reader.next(); e != XMLStreamConstants.END_DOCUMENT; e = reader.next()) {
         switch (e) { // Event.
             ...
         }
     }
     reader.close(); // Automatically recycles this writer. 
     in.close(); // Underlying input should be closed explicitly.
     

Version:

4.0, September 4, 2006

Author:

Jean-Marie Dautelle

Field Summary

Fields

Modifier and Type	Field and Description
static Configurable<Class<? extends XMLInputFactory>>	CLASS Holds the XMLInputFactory implementation (configurable).
static String	ENTITIES Property used to specify additional entities to be recognized by the readers (type: java.util.Map, default: null).
static String	IS_COALESCING The property that requires the parser to coalesce adjacent character data sections (type: Boolean, default: FALSE)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XMLInputFactory() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
abstract XMLStreamReader	createXMLStreamReader(InputStream stream) Returns a XML stream reader for the specified input stream (encoding autodetected).
abstract XMLStreamReader	createXMLStreamReader(InputStream stream, String encoding) Returns a XML stream reader for the specified input stream using the specified encoding.
abstract XMLStreamReader	createXMLStreamReader(Reader reader) Returns a XML stream reader for the specified I/O reader.
abstract Object	getProperty(String name) Gets the value of a feature/property from the underlying implementation.
abstract boolean	isPropertySupported(String name) Queries the set of properties that this factory supports.
static XMLInputFactory	newInstance() Returns a new instance of the CLASS input factory implementation which may be configurated by the user (see setProperty(String, Object)).
abstract void	setProperty(String name, Object value) Allows the user to set specific feature/property on the underlying implementation.

Methods inherited from class Object

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

Field Detail

CLASS

public static final Configurable<Class<? extends XMLInputFactory>> CLASS

Holds the XMLInputFactory implementation (configurable).

IS_COALESCING

public static final String IS_COALESCING

The property that requires the parser to coalesce adjacent character data sections (type: Boolean, default: FALSE)

See Also:

Constant Field Values

ENTITIES

public static final String ENTITIES

Property used to specify additional entities to be recognized by the readers (type: java.util.Map, default: null). For example:

     FastMap<String, String> HTML_ENTITIES = new FastMap<String, String>();
     HTML_ENTITIES.put("nbsp", " ");
     HTML_ENTITIES.put("copy", "©");
     HTML_ENTITIES.put("eacute", "é");
     ...
     XMLInputFactory factory = XMLInputFactory.newInstance();
     factory.setProperty(ENTITIES, HTML_ENTITIES);
 

See Also:

Constant Field Values

Constructor Detail

XMLInputFactory

protected XMLInputFactory()

Default constructor.

Method Detail

newInstance

public static XMLInputFactory newInstance()

Returns a new instance of the CLASS input factory implementation which may be configurated by the user (see setProperty(String, Object)). The input factory instance is allocated through ObjectFactory.getInstance(Class).

Returns:

a new factory instance.

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(Reader reader)
                                               throws XMLStreamException

Returns a XML stream reader for the specified I/O reader.

Parameters:

reader - the XML data to read from.

Throws:

XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(InputStream stream)
                                               throws XMLStreamException

Returns a XML stream reader for the specified input stream (encoding autodetected).

Parameters:

stream - the input stream to read from.

Throws:

XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(InputStream stream,
                                    String encoding)
                                               throws XMLStreamException

Returns a XML stream reader for the specified input stream using the specified encoding.

Parameters:

stream - the input stream to read from.

encoding - the character encoding of the stream.

Throws:

XMLStreamException

setProperty

public abstract void setProperty(String name,
               Object value)
                          throws IllegalArgumentException

Allows the user to set specific feature/property on the underlying implementation. The underlying implementation is not required to support every setting of every property in the specification and may use IllegalArgumentException to signal that an unsupported property may not be set with the specified value.

Parameters:

name - the name of the property.

value - the value of the property

Throws:

IllegalArgumentException - if the property is not supported.

getProperty

public abstract Object getProperty(String name)
                            throws IllegalArgumentException

Gets the value of a feature/property from the underlying implementation.

Parameters:

name - the name of the property (may not be null).

Returns:

the value of the property.

Throws:

IllegalArgumentException - if the property is not supported.

isPropertySupported

public abstract boolean isPropertySupported(String name)

Queries the set of properties that this factory supports.

Parameters:

name - the name of the property.

Returns:

true if the property is supported; false otherwise.