javolution.xml.stream

Class XMLOutputFactory

Object

XMLOutputFactory

public abstract class XMLOutputFactory
extends Object

The class represents the factory for getting XMLStreamWriter intances.

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

Usage example:

     // Lets format to an appendable.
     TextBuilder xml = new TextBuilder();
     AppendableWriter out = new AppendableWriter(xml);
     
     // Creates a factory producing writers using tab indentation.
     XMLOutpuFactory factory = XMLOutputFactory.newInstance();
     factory.setProperty(XMLOutputFactory.INDENTATION, "/t");
     
     // Creates a new writer (potentially recycled).
     XMLStreamWriter writer = factory.createXMLStreamReader(out);
     
     // Formats to XML.
     writer.writeStartDocument();
     writer.writeStartElement(...); 
     ...
     writer.close(); // Automatically recycles this writer. 
     out.close(); // Underlying output should be closed explicitly.
     
     // Displays the formatted output.
     System.out.println(xml);
     

Version:

4.0, September 4, 2006

Author:

Jean-Marie Dautelle

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTOMATIC_EMPTY_ELEMENTS Property indicating if the stream writers are allowed to automatically output empty elements when a start element is immediately followed by matching end element (type: Boolean, default: FALSE).
static Configurable<Class<? extends XMLOutputFactory>>	CLASS Holds the XMLOutputFactory implementation (configurable).
static String	INDENTATION Property used to specify an indentation string; non-null indentation forces the writer to write elements into separate lines (type: String, default: null).
static String	IS_REPAIRING_NAMESPACES Property used to set prefix defaulting on the output side (type: Boolean, default: FALSE).
static String	LINE_SEPARATOR Property used to specify the new line characters (type: String, default: "\n").
static String	NO_EMPTY_ELEMENT_TAG Property indicating if the stream writers are not allowed to use empty element tags (type: Boolean, default: FALSE).
static String	REPAIRING_PREFIX Property used to specify the prefix to be appended by a trailing part (a sequence number) in order to make it unique to be usable as a temporary non-colliding prefix when repairing namespaces (type: String, default: "ns").

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XMLOutputFactory() Default constructor.

Method Summary

Methods

Modifier and Type	Method and Description
abstract XMLStreamWriter	createXMLStreamWriter(OutputStream stream) Returns a XML stream writer to the specified output stream (UTF-8 encoding).
abstract XMLStreamWriter	createXMLStreamWriter(OutputStream stream, String encoding) Returns a XML stream writer to the specified output stream using the specified encoding.
abstract XMLStreamWriter	createXMLStreamWriter(Writer writer) Returns a XML stream writer to the specified i/o writer.
abstract Object	getProperty(String name) Gets a feature/property on the underlying implementation.
abstract boolean	isPropertySupported(String name) Queries the set of properties that this factory supports.
static XMLOutputFactory	newInstance() Returns a new instance of the CLASS output 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 features/properties 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 XMLOutputFactory>> CLASS

Holds the XMLOutputFactory implementation (configurable).

IS_REPAIRING_NAMESPACES

public static final String IS_REPAIRING_NAMESPACES

Property used to set prefix defaulting on the output side (type: Boolean, default: FALSE).

See Also:

Constant Field Values

REPAIRING_PREFIX

public static final String REPAIRING_PREFIX

Property used to specify the prefix to be appended by a trailing part (a sequence number) in order to make it unique to be usable as a temporary non-colliding prefix when repairing namespaces (type: String, default: "ns").

See Also:

Constant Field Values

INDENTATION

public static final String INDENTATION

Property used to specify an indentation string; non-null indentation forces the writer to write elements into separate lines (type: String, default: null).

See Also:

Constant Field Values

LINE_SEPARATOR

public static final String LINE_SEPARATOR

Property used to specify the new line characters (type: String, default: "\n").

See Also:

Constant Field Values

AUTOMATIC_EMPTY_ELEMENTS

public static final String AUTOMATIC_EMPTY_ELEMENTS

Property indicating if the stream writers are allowed to automatically output empty elements when a start element is immediately followed by matching end element (type: Boolean, default: FALSE).

See Also:

Constant Field Values

NO_EMPTY_ELEMENT_TAG

public static final String NO_EMPTY_ELEMENT_TAG

Property indicating if the stream writers are not allowed to use empty element tags (type: Boolean, default: FALSE). When set, this property forces the use of start/end element tag (e.g. i.e. "<empty />" replaced by "<empty></empty>"), This property takes precedence over AUTOMATIC_EMPTY_ELEMENTS.

See Also:

Constant Field Values

Constructor Detail

XMLOutputFactory

protected XMLOutputFactory()

Default constructor.

Method Detail

newInstance

public static XMLOutputFactory newInstance()

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

Returns:

a new factory instance.

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(Writer writer)
                                               throws XMLStreamException

Returns a XML stream writer to the specified i/o writer.

Parameters:

writer - the writer to write to.

Throws:

XMLStreamException

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(OutputStream stream)
                                               throws XMLStreamException

Returns a XML stream writer to the specified output stream (UTF-8 encoding).

Parameters:

stream - the stream to write to.

Throws:

XMLStreamException

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(OutputStream stream,
                                    String encoding)
                                               throws XMLStreamException

Returns a XML stream writer to the specified output stream using the specified encoding.

Parameters:

stream - the stream to write to.

encoding - the encoding to use.

Throws:

XMLStreamException

setProperty

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

Allows the user to set specific features/properties on the underlying implementation.

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 a feature/property on the underlying implementation.

Parameters:

name - the name of the property

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 (may not be null).

Returns:

true if the property is supported; false otherwise.