Package org.znerd.xmlenc

Class XMLEncoder

java.lang.Object

org.znerd.xmlenc.XMLEncoder

public class XMLEncoder
extends Object

Encodes character streams for an XML document.

The following encodings are supported:

• UTF-8
• UTF-16
• US-ASCII, with alias ASCII
• all ISO-8859 encodings

Since:

xmlenc 0.1

Version:

$Revision: 1.210 $ $Date: 2005/10/24 09:54:53 $

Author:

Ernst de Haan (ernst.dehaan@nl.wanadoo.com), Jochen Schwoerer (j.schwoerer [at] web.de), Anthony Goubard (anthony.goubard@nl.wanadoo.com)

Constructor Summary

Constructors

Constructor	Description
XMLEncoder(String encoding)	Deprecated. Deprecated since xmlenc 0.47.

Method Summary

Modifier and Type	Method	Description
void	attribute(Writer out, String name, String value, char quotationMark, boolean escapeAmpersands)	Writes an attribute assignment.
void	declaration(Writer out)	Writes an XML declaration.
static XMLEncoder	getEncoder(String encoding)	Retrieves an XMLEncoder for the specified encoding.
String	getEncoding()	Returns the encoding.
void	text(Writer out, char c)	Deprecated. Deprecated since xmlenc 0.51.
void	text(Writer out, char[] ch, int start, int length, boolean escapeAmpersands)	Writes text from the specified character array.
void	text(Writer out, char c, boolean escapeAmpersands)	Writes the specified character.
void	text(Writer out, String text, boolean escapeAmpersands)	Writes the specified text.
void	whitespace(Writer out, char[] ch, int start, int length)	Writes whitespace from the specified character array.
void	whitespace(Writer out, String s)	Writes the specified whitespace string.

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLEncoder

public XMLEncoder(String encoding)
           throws IllegalArgumentException,
                  UnsupportedEncodingException

Deprecated.

Deprecated since xmlenc 0.47. Use the factory method getEncoder(String) instead.

Constructs a new XMLEncoder instance.

Parameters:

encoding - the name of the encoding, not null.

Throws:

IllegalArgumentException - if encoding == null.

UnsupportedEncodingException - if the specified encoding is not supported.

Method Detail

getEncoder

public static final XMLEncoder getEncoder(String encoding)
                                   throws IllegalArgumentException,
                                          UnsupportedEncodingException

Retrieves an XMLEncoder for the specified encoding. If no suitable instance can be returned, then an exception is thrown.

Parameters:

encoding - the name of the encoding, not null.

Returns:

an XMLEncoder instance that matches the specified encoding, never null.

Throws:

IllegalArgumentException - if encoding == null.

UnsupportedEncodingException - if the specified encoding is not supported.

getEncoding

public String getEncoding()

Returns the encoding.

Returns:

the encoding passed to the constructor, never null.

declaration

public void declaration(Writer out)
                 throws NullPointerException,
                        IOException

Writes an XML declaration.

Parameters:

out - the character stream to write to, not null.

Throws:

NullPointerException - if out == null.

IOException - if an I/O error occurs.

text

public void text(Writer out,
                 String text,
                 boolean escapeAmpersands)
          throws NullPointerException,
                 InvalidXMLException,
                 IOException

Writes the specified text. Any characters that are non-printable in this encoding will be escaped.

It must be specified whether ampersands should be escaped. Unless ampersands are escaped, entity references can be written.

Parameters:

out - the character stream to write to, not null.

text - the text to be written, not null.

escapeAmpersands - flag that indicates whether ampersands should be escaped.

Throws:

NullPointerException - if out == null || text == null.

InvalidXMLException - if the specified text contains an invalid character.

IOException - if an I/O error occurs.

text

public void text(Writer out,
                 char[] ch,
                 int start,
                 int length,
                 boolean escapeAmpersands)
          throws NullPointerException,
                 IndexOutOfBoundsException,
                 InvalidXMLException,
                 IOException

Writes text from the specified character array. Any characters that are non-printable in this encoding will be escaped.

It must be specified whether ampersands should be escaped. Unless ampersands are escaped, entity references can be written.

Parameters:

out - the character stream to write to, not null.

ch - the character array from which to retrieve the text to be written, not null.

start - the start index into ch, must be >= 0.

length - the number of characters to take from ch, starting at the start index.

escapeAmpersands - flag that indicates if ampersands should be escaped.

Throws:

NullPointerException - if out == null || ch == null.

IndexOutOfBoundsException - if start < 0 || start + length > ch.length; this may not be checked before the character stream is written to, so this may cause a partial failure.

InvalidXMLException - if the specified text contains an invalid character.

IOException - if an I/O error occurs.

text

public void text(Writer out,
                 char c)
          throws InvalidXMLException,
                 IOException

Deprecated.

Deprecated since xmlenc 0.51. Use the text method text(Writer, char, boolean) instead.

Writes the specified character. If the character is non-printable in this encoding, then it will be escaped.

It is safe for this method to assume that the specified character does not need to be escaped unless the encoding does not support the character.

Parameters:

out - the character stream to write to, not null.

c - the character to be written.

Throws:

InvalidXMLException - if the specified text contains an invalid character.

IOException - if an I/O error occurs.

text

public void text(Writer out,
                 char c,
                 boolean escapeAmpersands)
          throws InvalidXMLException,
                 IOException

Writes the specified character. If the character is non-printable in this encoding, then it will be escaped.

It is safe for this method to assume that the specified character does not need to be escaped unless the encoding does not support the character.

Parameters:

out - the character stream to write to, not null.

c - the character to be written.

escapeAmpersands - flag that indicates if ampersands should be escaped.

Throws:

InvalidXMLException - if the specified text contains an invalid character.

IOException - if an I/O error occurs.

whitespace

public void whitespace(Writer out,
                       String s)
                throws NullPointerException,
                       InvalidXMLException,
                       IOException

Writes the specified whitespace string.

Parameters:

out - the character stream to write to, not null.

s - the character string to be written, not null.

Throws:

NullPointerException - if out == null || s == null.

InvalidXMLException - if the specified character string contains a character that is invalid as whitespace.

IOException - if an I/O error occurs.

whitespace

public void whitespace(Writer out,
                       char[] ch,
                       int start,
                       int length)
                throws NullPointerException,
                       IndexOutOfBoundsException,
                       InvalidXMLException,
                       IOException

Writes whitespace from the specified character array.

Parameters:

out - the character stream to write to, not null.

ch - the character array from which to retrieve the text to be written, not null.

start - the start index into ch, must be >= 0.

length - the number of characters to take from ch, starting at the start index.

Throws:

NullPointerException - if out == null || ch == null.

IndexOutOfBoundsException - if start < 0 || start + length > ch.length; this may not be checked before the character stream is written to, so this may cause a partial failure.

InvalidXMLException - if the specified character array contains a character that is invalid as whitespace.

IOException - if an I/O error occurs.

attribute

public void attribute(Writer out,
                      String name,
                      String value,
                      char quotationMark,
                      boolean escapeAmpersands)
               throws NullPointerException,
                      IOException

Writes an attribute assignment.

Parameters:

out - the character stream to write to, not null.

name - the name of the attribute, not null.

value - the value of the attribute, not null.

quotationMark - the quotation mark, must be either the apostrophe ('\'') or the quote character ('"').

Throws:

NullPointerException - if out == null || value == null.

IllegalArgumentException - if quotationMark != '\'' && quotationMark != '"'.

IOException - if an I/O error occurs.