com.mucommander.xml
Class XmlWriter

java.lang.Object
  com.mucommander.xml.XmlWriter

public class XmlWriter
extends java.lang.Object

Used to write pretty-printed XML content.

Application writers should keep in mind that this class does not perform any sort of coherency check, and will not prevent them from closing elements they haven't opened yet, or any other thing that would make the XML output invalid.

Author:

Nicolas Rinaudo

Field Summary

static java.lang.String	AVAILABILITY_PUBLIC Identifier for publicly accessible objects.
static java.lang.String	AVAILABILITY_SYSTEM Identifier for system resources.
static java.lang.String	DEFAULT_ENCODING Default output encoding.

Constructor Summary

XmlWriter(java.io.File file)
Creates an XmlWriter that will write to the specified file.

XmlWriter(java.io.File file, java.lang.String encoding)
Creates an XmlWriter that will write to the specified file using the specified encoding.

XmlWriter(java.io.OutputStream stream)
Creates an XmlWriter that will write to the specified output stream.

XmlWriter(java.io.OutputStream stream, java.lang.String encoding)
Creates an XmlWriter that will write to the specified stream using the specified encoding.

Method Summary

void	close() Closes the XML stream.
void	endElement(java.lang.String name) Writes an element closing sequence.
java.lang.String	escape(java.lang.String data) Escapes XML content, replacing special characters by their proper value.
void	println() Prints a line break.
void	startElement(java.lang.String name) Writes an element opening sequence.
void	startElement(java.lang.String name, boolean lineBreak) Writes an element opening sequence.
void	startElement(java.lang.String name, XmlAttributes attributes) Writes an element opening sequence.
void	startElement(java.lang.String name, XmlAttributes attributes, boolean lineBreak) Writes an element opening sequence.
void	writeCData(java.lang.String cdata) Writes the specified CDATA to the XML stream.
void	writeDocType(java.lang.String topElement, java.lang.String availability, java.lang.String description, java.lang.String url) Writes the document type declaration of the XML file.
void	writeStandAloneElement(java.lang.String name) Writes a stand-alone element.
void	writeStandAloneElement(java.lang.String name, XmlAttributes attributes) Writes a stand-alone element.

Methods inherited from class java.lang.Object

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

Field Detail

AVAILABILITY_PUBLIC

public static final java.lang.String AVAILABILITY_PUBLIC

Identifier for publicly accessible objects.

See Also:

Constant Field Values

AVAILABILITY_SYSTEM

public static final java.lang.String AVAILABILITY_SYSTEM

Identifier for system resources.

See Also:

Constant Field Values

DEFAULT_ENCODING

public static final java.lang.String DEFAULT_ENCODING

Default output encoding.

See Also:

Constant Field Values

Constructor Detail

XmlWriter

public XmlWriter(java.io.File file)
          throws java.io.IOException,
                 java.io.FileNotFoundException

Creates an XmlWriter that will write to the specified file.

This is a convenience constructor and is strictly equivalent to XmlWriter(new FileOutputStream(file), DEFAULT_ENCODING).

Parameters:

file - where to write XML output to.

Throws:

java.io.FileNotFoundException - if file could not be found.

java.io.IOException - if an I/O error occurs.

XmlWriter

public XmlWriter(java.io.File file,
                 java.lang.String encoding)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 java.io.UnsupportedEncodingException

Creates an XmlWriter that will write to the specified file using the specified encoding.

This is a convenience constructor and is strictly equivalent to XmlWriter(new FileOutputStream(file), encoding).

Parameters:

file - where to write XML output to.

encoding - encoding to use when writing the XML content.

Throws:

java.io.FileNotFoundException - if file could not be found.

java.io.UnsupportedEncodingException - if encoding is not supported.

java.io.IOException - if an I/O error occurs.

XmlWriter

public XmlWriter(java.io.OutputStream stream)
          throws java.io.IOException

Creates an XmlWriter that will write to the specified output stream.

This is a convenience constructor and is strictly equivalent to XmlWriter(stream, DEFAULT_ENCODING).

Parameters:

stream - where to write XML output to.

Throws:

java.io.IOException - if an I/O error occurs.

XmlWriter

public XmlWriter(java.io.OutputStream stream,
                 java.lang.String encoding)
          throws java.io.UnsupportedEncodingException,
                 java.io.IOException

Creates an XmlWriter that will write to the specified stream using the specified encoding.

Parameters:

stream - where to write XML output to.

encoding - encoding to use when writing the XML content.

Throws:

java.io.UnsupportedEncodingException - if encoding is not supported.

java.io.IOException - if an I/O error occurs.

Method Detail

writeDocType

public void writeDocType(java.lang.String topElement,
                         java.lang.String availability,
                         java.lang.String description,
                         java.lang.String url)
                  throws java.io.IOException

Writes the document type declaration of the XML file.

For the generated XML content to be valid, application writers should make sure that this is the very first method they call. This class doesn't ensure coherency and won't complain if the DOCTYPE statement is the last in the file.

Both description and url can be set to null. If so, they will just be ignored.

Parameters:

topElement - label of the top element in the XML file.

availability - availability of the document (expected to be either AVAILABILITY_PUBLIC or AVAILABILITY_SYSTEM, but this is not enforced).

description - description of the file (see DOCTYPE specifications for more information).

url - URL at which the DTD of the XML file can be downloaded.

Throws:

java.io.IOException - if an I/O error occurs.

startElement

public void startElement(java.lang.String name)
                  throws java.io.IOException

Writes an element opening sequence.

This is a convenience method and is strictly equivalent to calling startElement(name, false).

Parameters:

name - name of the element to open.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String,XmlAttributes), writeStandAloneElement(String), writeStandAloneElement(String,XmlAttributes)

startElement

public void startElement(java.lang.String name,
                         boolean lineBreak)
                  throws java.io.IOException

Writes an element opening sequence.

Elements opened using this method will not have any attribute, and will need to be closed using an endElement call.

Parameters:

name - name of the element to open.

lineBreak - if true, a line break will be printed after the element declaration.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String,XmlAttributes), writeStandAloneElement(String), writeStandAloneElement(String,XmlAttributes)

writeStandAloneElement

public void writeStandAloneElement(java.lang.String name)
                            throws java.io.IOException

Writes a stand-alone element.

Elements opened using this method will not have any attributes, and will be closed immediately.

A line break will always be printed after a stand-alone element.

Parameters:

name - name of the element to write.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String,XmlAttributes), startElement(String), writeStandAloneElement(String)

startElement

public void startElement(java.lang.String name,
                         XmlAttributes attributes)
                  throws java.io.IOException

Writes an element opening sequence.

This is a covenience method and is stricly equivalent to calling startElement(name, attributes, false).

Parameters:

name - name of the element to open.

attributes - attributes that this element will have.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String), writeStandAloneElement(String), writeStandAloneElement(String,XmlAttributes)

startElement

public void startElement(java.lang.String name,
                         XmlAttributes attributes,
                         boolean lineBreak)
                  throws java.io.IOException

Writes an element opening sequence.

Elements opened using this method will need to be closed using an endElement call.

Parameters:

name - name of the element to open.

attributes - attributes that this element will have.

lineBreak - if true, a line break will be printed after the element declaration.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String), writeStandAloneElement(String), writeStandAloneElement(String,XmlAttributes)

writeStandAloneElement

public void writeStandAloneElement(java.lang.String name,
                                   XmlAttributes attributes)
                            throws java.io.IOException

Writes a stand-alone element.

Elements opened using this method will not need to be closed

A line break will always be printed after a stand-alone element.

Parameters:

name - name of the element to write.

attributes - attributes that this element will be closed immediately.

Throws:

java.io.IOException - if an I/O error occurs.

See Also:

startElement(String), startElement(String,XmlAttributes), writeStandAloneElement(String)

endElement

public void endElement(java.lang.String name)
                throws java.io.IOException

Writes an element closing sequence.

Parameters:

name - name of the element to close.

Throws:

java.io.IOException - if an I/O error occurs.

writeCData

public void writeCData(java.lang.String cdata)
                throws java.io.IOException

Writes the specified CDATA to the XML stream.

Parameters:

cdata - content to write to the XML stream.

Throws:

java.io.IOException - if an I/O error occurs.

escape

public java.lang.String escape(java.lang.String data)
                        throws java.io.IOException

Escapes XML content, replacing special characters by their proper value.

Parameters:

data - data to escape.

Returns:

the escaped content.

Throws:

java.io.IOException - if an I/O error occurs.

println

public void println()
             throws java.io.IOException

Prints a line break.

Throws:

java.io.IOException - if an I/O error occurs.

close

public void close()
           throws java.io.IOException

Closes the XML stream.

Throws:

java.io.IOException - if an I/O error occurs.