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)

Field Summary

private String	_encoding The name of the encoding.
private char[]	_encodingCharArray The name of the encoding as a character array.
private boolean	_sevenBitEncoding Flag that indicates whether the encoding is based on the ISO 646 character set.
private static char[]	AMPERSAND_HASH Character array representing the string "&#".
private static char[]	DECLARATION_END The last part of a declaration, after the encoding.
private static int	DECLARATION_END_LENGTH The length of DECLARATION_END.
private static char[]	DECLARATION_START The first part of a declaration, before the encoding.
private static int	DECLARATION_START_LENGTH The length of DECLARATION_START.
private static char[]	EQUALS_APOSTROPHE Character array representing the string "='".
private static char[]	EQUALS_QUOTE Character array representing the string "=\"".
private static char[]	ESC_AMPERSAND Character array representing the string "&".
private static char[]	ESC_APOSTROPHE Character array representing the string "'".
private static char[]	ESC_GREATER_THAN Character array representing the string ">".
private static char[]	ESC_LESS_THAN Character array representing the string "<".
private static char[]	ESC_QUOTE Character array representing the string "&apos;".

Constructor Summary

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

Method Summary

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. Use the text method text(Writer, char, boolean) instead.
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

Field Detail

DECLARATION_START

private static final char[] DECLARATION_START

The first part of a declaration, before the encoding.

DECLARATION_START_LENGTH

private static final int DECLARATION_START_LENGTH

The length of DECLARATION_START.

DECLARATION_END

private static final char[] DECLARATION_END

The last part of a declaration, after the encoding.

DECLARATION_END_LENGTH

private static final int DECLARATION_END_LENGTH

The length of DECLARATION_END.

ESC_GREATER_THAN

private static final char[] ESC_GREATER_THAN

Character array representing the string ">".

ESC_LESS_THAN

private static final char[] ESC_LESS_THAN

Character array representing the string "<".

ESC_AMPERSAND

private static final char[] ESC_AMPERSAND

Character array representing the string "&".

ESC_APOSTROPHE

private static final char[] ESC_APOSTROPHE

Character array representing the string "'".

ESC_QUOTE

private static final char[] ESC_QUOTE

Character array representing the string "'".

AMPERSAND_HASH

private static final char[] AMPERSAND_HASH

Character array representing the string "&#".

EQUALS_APOSTROPHE

private static final char[] EQUALS_APOSTROPHE

Character array representing the string "='".

EQUALS_QUOTE

private static final char[] EQUALS_QUOTE

Character array representing the string "=\"".

_encoding

private final String _encoding

The name of the encoding. Cannot be null.

_encodingCharArray

private final char[] _encodingCharArray

The name of the encoding as a character array. Cannot be null.

_sevenBitEncoding

private final boolean _sevenBitEncoding

Flag that indicates whether the encoding is based on the ISO 646 character set. The value is true if the encoding is a 7 bit encoding, or false if the encoding supports all Unicode characters.

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.