org.znerd.xmlenc
Class XMLEncoder

java.lang.Object
  |
  +--org.znerd.xmlenc.XMLEncoder

public abstract class XMLEncoder
extends Object

Encodes character streams for an XML document.

Since:
xmlenc 0.1
Version:
$Revision: 1.203 $ $Date: 2004/03/17 21:46:44 $
Author:
Ernst de Haan (znerd@FreeBSD.org), Jochen Schwoerer (j.schwoerer [at] web.de)

Constructor Summary
protected XMLEncoder()
          Constructs a new XMLEncoder.
 
Method Summary
 void attribute(Writer out, String name, String value, char quotationMark, boolean escapeAmpersands)
          Writes an attribute assignment.
abstract  void declaration(Writer out)
          Writes an XML declaration.
static XMLEncoder getEncoder(String encoding)
          Retrieves an XMLEncoder for the specified encoding.
abstract  String getEncoding()
          Returns the encoding of this outputter.
abstract  void text(Writer out, char c)
          Writes the specified character to the output stream.
 void text(Writer out, char[] ch, int start, int length, boolean escapeAmpersands)
          Writes the text in the specified character array to the output stream.
 void text(Writer out, String text, boolean escapeAmpersands)
          Writes the specified text to the output stream.
 void whitespace(Writer out, char[] ch, int start, int length)
          Writes the whitespace in the specified character array to the output stream.
 void whitespace(Writer out, String s)
          Writes the whitespace in the specified character string to the output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLEncoder

protected XMLEncoder()
Constructs a new XMLEncoder.
Method Detail

getEncoder

public static final XMLEncoder getEncoder(String encoding)
                                   throws IllegalArgumentException,
                                          UnsupportedEncodingException
Retrieves an XMLEncoder for the specified encoding. If no suitable encoder can be found, then an exception is thrown.
Parameters:
encoding - the name of the encoding, not null.
Returns:
an encoder for the specified encoding, never null.
Throws:
IllegalArgumentException - if encoding == null.
UnsupportedEncodingException - if the specified encoding is not supported.

getEncoding

public abstract String getEncoding()
Returns the encoding of this outputter.
Returns:
the encoding of this encoding, never null.

text

public void text(Writer out,
                 String text,
                 boolean escapeAmpersands)
          throws NullPointerException,
                 InvalidXMLException,
                 IOException
Writes the specified text to the output stream. Any characters that are non-printable in this character set will be escaped.

It must be specified whether ampersands should be escaped. Only if ampersands are escaped, entity references can be printed.

Parameters:
out - the output stream to print to, not null.
text - the text to be printed.
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 the text in the specified character array to the output stream. Any characters that are non-printable in this character set will be escaped.

It must be specified whether ampersands should be escaped. Only if ampersands are escaped, entity references can be printed.

Parameters:
out - the output stream to print to, not null.
ch - the array from which to retrieve the text to be printed.
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.
InvalidXMLException - if the specified text contains an invalid character.
IOException - if an I/O error occurs.

text

public abstract void text(Writer out,
                          char c)
                   throws IOException
Writes the specified character to the output stream. If the character is non-printable in this character set, 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 output stream to print to, not null.
c - the character to be printed.
Throws:
IOException - if an I/O error occurs.

declaration

public abstract void declaration(Writer out)
                          throws NullPointerException,
                                 IOException
Writes an XML declaration.
Parameters:
out - the Writer to write the declaration to, not null.
Throws:
NullPointerException - if out == null.
IOException - if an I/O error occurs.

whitespace

public void whitespace(Writer out,
                       String s)
                throws NullPointerException,
                       InvalidXMLException,
                       IOException
Writes the whitespace in the specified character string to the output stream.
Parameters:
out - the output stream to print to, not null.
s - the character string to print.
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 the whitespace in the specified character array to the output stream.
Parameters:
out - the output stream to print to, not null.
ch - the array from which to retrieve the text to be printed.
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.
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 Writer to write the declaration to, should not be null.
name - the name of the attribute, should not be null.
value - the value of the attribute, should not be 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.


See http://xmlenc.sourceforge.net/.